PyInstaller

Installation and Setup

Install the CLI from PyPI:

• Windows
• Linux + macOS

PS> py -m pip install pyinstaller
PS> pyinstaller --version

$ python -m pip install pyinstaller
$ pyinstaller --version

Use a clean virtual environment for reproducible builds. Build on each target operating system since cross compilation isn’t supported.

Key Features

• Creates self-contained executables with either one-directory or a single-file layout.
• Analyzes imports and bundles the needed parts of the interpreter and libraries.
• Supports data files, binary extensions, and hidden imports with a flexible CLI.
• Records build configuration in a .spec file that you can edit and reuse.
• Provides a hook system that improves detection for many popular libraries.

Usage

Build an executable in a dist folder:

$ pyinstaller app.py

Create a single file bundle that unpacks at runtime:

$ pyinstaller --onefile app.py

Customize the app name and icon and disable the console window on GUI apps:

$ pyinstaller --onefile --name AppName --icon app.ico --noconsole app.py

Include data files:

• Windows
• Linux + macOS

PS> pyinstaller --add-data "config.yaml;." app.py

$ pyinstaller --add-data "config.yaml:." app.py

Generate and edit a spec file, then rebuild from it:

$ pyinstaller --onefile --name AppName app.py   # Writes AppName.spec
$ pyinstaller AppName.spec                      # Reproducible rebuild

Clean previous build output and skip confirmation prompts:

$ pyinstaller --clean --noconfirm --onefile app.py

The executables appear under dist/.

Related Resources

Tutorial

Using PyInstaller to Easily Distribute Python Applications

In this step-by-step tutorial, you'll learn how to use PyInstaller to turn your Python application into an executable with no dependencies or installation required. This is great if you want to distribute applications to users who may or may not be Python developers.

intermediate best-practices