pyinstaller

library6.19.0pypypiunverified

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.

devops

pip install pyinstaller

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYINSTALLER

pyinstaller

devopspythonv6.19.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.

pyinstaller --version

Debug

Known issues

breakingPython 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.

affects: All major version upgrades (e.g., from v5.x to v6.x)

deprecatedThe `--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`

affects: PyInstaller >= 5.0

gotchaMissing 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.

affects: All versions

gotchaAntivirus 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.

affects: All versions, especially with `--onefile`

Errors

Common errors & fixes

Failed to execute script <script_name>

This generic runtime error indicates that the bundled application encountered an unhandled exception during execution, often a `ModuleNotFoundError` or `FileNotFoundError`, but the specific traceback is suppressed.

fix

Run the executable from the command line (e.g., `my_app.exe` on Windows or `./my_app` on macOS/Linux) or re-bundle without the `--windowed` option to see the detailed Python traceback, which will reveal the underlying error. Alternatively, add `--debug` during the build process to get more verbose output during execution.

ModuleNotFoundError: No module named '<module_name>'

PyInstaller failed to automatically detect and include a Python module that your script or one of its dependencies uses, often due to 'hidden imports' or a misconfigured Python environment during the build.

fix

Add the missing module explicitly using the `--hidden-import <module_name>` option in your PyInstaller command (e.g., `pyinstaller --onefile --hidden-import='pandas.io.excel._openpyxl' your_script.py`). Ensure PyInstaller is run from a virtual environment where all necessary packages are installed.

FileNotFoundError: [Errno 2] No such file or directory: '<file_path>'

The bundled executable cannot locate a data file (e.g., image, configuration, font, or DLL) that your application needs, typically because it was not included in the PyInstaller bundle or is referenced incorrectly with an absolute path.

fix

Include data files using the `--add-data 'source;destination'` option (e.g., `pyinstaller --add-data 'images/*.png;images' your_script.py`) or by modifying the `.spec` file's `datas` array. Always use relative paths within your script to refer to these bundled files.

ImportErrorWhenRunningHook: Failed to import module __PyInstaller_hooks_0_<module_name>

PyInstaller's internal hook mechanism failed when trying to process a specific Python package, often because the hook is incompatible with the installed version of the package or Python, or the package uses complex import patterns not fully handled by PyInstaller's default analysis.

fix

Try updating `pyinstaller` and `pyinstaller-hooks-contrib` to their latest versions: `pip install --upgrade pyinstaller pyinstaller-hooks-contrib`. If the issue persists, consider downgrading the problematic third-party library or checking PyInstaller's documentation/GitHub issues for a specific workaround or a custom hook for that module.

Upgrade

Version history

6.19.0latest on PyPI · released Feb 14, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/pyinstaller/pyinstaller ↗

packagehttps://pypi.org/project/pyinstaller/ ↗

homepagehttps://pyinstaller.org ↗

docshttps://pyinstaller.org ↗

changeloghttps://pyinstaller.org/en/stable/CHANGES.html ↗