PyInstaller

6.19.0 · active · verified Thu Apr 09

PyInstaller is a versatile tool that bundles a Python application and all its dependencies into a single package, often a standalone executable. This allows distribution of Python applications to users without requiring them to install a Python interpreter or any modules. The current version is 6.19.0, and the project typically releases minor versions every 2-3 months and major versions annually.

Warnings

breaking Python Version Compatibility: PyInstaller regularly updates its supported Python versions. Upgrading PyInstaller might require upgrading your Python environment if you're on an older, no longer supported version.
Fix: Always check PyInstaller's `requires_python` metadata (e.g., on PyPI) or the official documentation for the version you intend to use. Ensure your Python environment meets the requirements before upgrading PyInstaller.
deprecated The `--add-data` and `--add-binary` command-line options syntax for specifying source and destination paths was modified starting with PyInstaller 5.0 to improve cross-platform consistency. The old syntax (e.g., `SRC;DEST` for Windows or `SRC:DEST` for Unix-like systems) is deprecated and will emit warnings.
Fix: Adopt the new syntax: `--add-data SOURCE_PATH{os.pathsep}DEST_PATH` (or explicitly `SOURCE_PATH:DEST_PATH` for Unix-like or `SOURCE_PATH;DEST_PATH` for Windows) and ensure the separator matches the target platform for cross-platform builds. For example, `pyinstaller --add-data 'my_data.txt:.' my_app.py`
gotcha Missing runtime dependencies or 'hidden imports': Complex libraries often use dynamic imports or C extensions that PyInstaller might not automatically detect. This leads to runtime errors in the bundled application.
Fix: Use the `--hidden-import` option to explicitly tell PyInstaller about modules it should include (e.g., `pyinstaller --hidden-import=sklearn.utils my_app.py`). For more complex scenarios, consider writing custom hook files or reviewing PyInstaller's extensive list of built-in hooks for popular libraries.
gotcha Antivirus software false positives: Executables bundled with `--onefile` (a single executable file) can sometimes be flagged by antivirus software as suspicious, even if they are legitimate, due to their compressed nature and unpack-on-run behavior.
Fix: If possible, distribute with `--onedir` (a directory containing the executable and its dependencies), which is less prone to false positives. For `--onefile` applications, you may need to instruct users to create an antivirus exception or digitally sign your executable, although signing does not guarantee avoidance of all false positives.

Install

pip install pyinstaller Install PyInstaller

Quickstart

PyInstaller is primarily a command-line tool. This example demonstrates how to create a simple Python script and the typical command used to bundle it into a standalone executable. After running `pyinstaller my_app.py` in your terminal, a `dist` folder will be created containing the executable.

import os

# Create a dummy Python script for demonstration
with open('my_app.py', 'w') as f:
    f.write("""
import sys
import os

def main():
    print("Hello from my bundled app!")
    print(f"Running from: {os.path.dirname(sys.executable)}")

if __name__ == '__main__':
    main()
""")

# Run PyInstaller via command line (most common use case)
# For programmatic use, you'd typically call PyInstaller.__main__.run(['my_app.py'])
# This is a shell command, not Python code to be executed directly in this context.
# You would run 'pyinstaller my_app.py' in your terminal.

view raw JSON →