Packaging a Python Application into a Single Executable (.exe) with PyInstaller

This guide explains how to package your Python application into a standalone Windows executable file (.exe) using the PyInstaller library. This allows you to distribute your Python app without requiring users to have Python installed.

Prerequisites

You have a working Python project with a virtual environment activated.
Your app runs correctly inside the virtual environment.
Basic familiarity with the command line/terminal.
This guide assumes you are on a Windows machine or are creating a Windows executable (the .exe).

1. Activate Your Virtual Environment

If not already activated, activate your virtual environment where your project dependencies (including PyInstaller) will be installed.

For .venv folder on Windows Command Prompt:

.venv\Scripts\activate.bat

On Windows PowerShell:

.venv\Scripts\Activate.ps1

2. Install PyInstaller

Install the PyInstaller package inside your virtual environment:

pip install pyinstaller

3. Package Your Python Script

Navigate to your project directory containing your main script (app.py).

Run PyInstaller with the --onefile option to create a single executable file:

pyinstaller --onefile app.py

NOTES:
- You can replace pyinstaller with python -m PyInstaller or python3 -m PyInstaller if pyinstaller command is not found. - The --onefile flag bundles everything into one executable file instead of a folder with dependencies.

4. Locate the Executable File

After PyInstaller finishes, it creates several new folders and files.

Your standalone .exe file will be located in the dist folder inside your project directory.

Example path:

my_python_project/
├─ dist/
│  └─ app.exe
├─ build/
├─ app.py
├─ app.spec
└─ ...

5. Test the Executable

Run the executable by double-clicking dist\app.exe or running it from the command line:

dist\app.exe

It should behave the same as running your Python script and display the expected output.

6. Optional PyInstaller Flags

Here are some useful PyInstaller command options you might consider:

--onefile: Bundle everything into a single executable file (instead of a folder).
--windowed or --noconsole: Prevent a console window from appearing.
--windowed is typically used for GUI apps on Windows and macOS.
--noconsole is an alias on Windows for the same effect, hiding the console.
--icon=path/to/icon.ico: Include a custom icon for your executable.
--name=YourAppName: Specify a custom name for the executable file.

Example combining options:

pyinstaller --onefile --noconsole --name MyApp --icon myicon.ico my_script.py

7. Cleaning Up

PyInstaller generates build files and spec files which are sometimes unnecessary after creating your executable.
To clean up, you can delete the build folder and .spec file manually if you like.

Summary

Step	Command Example
Activate virtualenv	`.venv\Scripts\activate.bat` (Windows CMD)
Install PyInstaller	`pip install pyinstaller`
Create single exe	`pyinstaller --onefile app.py`
Run executable	`dist\app.exe`

You now have a standalone Windows executable of your Python application ready for distribution!

Troubleshooting Tips

If the executable crashes or behaves unexpectedly, run it from the command line to see error outputs.
Some libraries require additional PyInstaller options or hooks; consult the PyInstaller documentation for advanced cases.
Make sure to test on a clean Windows machine or VM that doesn't have Python installed to ensure your .exe works standalone.