{"id":1651,"library":"pyinstaller","title":"PyInstaller","description":"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.","status":"active","version":"6.19.0","language":"python","source_language":"en","source_url":"https://github.com/pyinstaller/pyinstaller","tags":["packaging","executable","distribution","installer","standalone"],"install":[{"cmd":"pip install pyinstaller","lang":"bash","label":"Install PyInstaller"}],"dependencies":[],"imports":[],"quickstart":{"code":"import os\n\n# Create a dummy Python script for demonstration\nwith open('my_app.py', 'w') as f:\n    f.write(\"\"\"\nimport sys\nimport os\n\ndef main():\n    print(\"Hello from my bundled app!\")\n    print(f\"Running from: {os.path.dirname(sys.executable)}\")\n\nif __name__ == '__main__':\n    main()\n\"\"\")\n\n# Run PyInstaller via command line (most common use case)\n# For programmatic use, you'd typically call PyInstaller.__main__.run(['my_app.py'])\n# This is a shell command, not Python code to be executed directly in this context.\n# You would run 'pyinstaller my_app.py' in your terminal.","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All major version upgrades (e.g., from v5.x to v6.x)"},{"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`","message":"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.","severity":"deprecated","affected_versions":"PyInstaller >= 5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially with `--onefile`"}],"env_vars":null,"search_vec":"'-3':57 '2':56 '6.19.0':47 'allow':25 'annual':62 'applic':11,29 'bundl':8 'current':44 'depend':15 'distribut':26,65 'everi':55 'execut':23,64 'instal':36,66 'interpret':39 'major':60 'minor':53 'modul':42 'month':58 'often':20 'packag':19,63 'project':50 'pyinstal':1,2 'python':10,28,38 'releas':52 'requir':33 'singl':18 'standalon':22,67 'tool':6 'typic':51 'user':31 'versatil':5 'version':45,54,61 'without':32","created_at":"2026-04-09T03:57:16.569617+00:00","updated_at":"2026-04-16T18:30:01.894477+00:00","problems":[{"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.","cause":"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.","error":"Failed to execute script <script_name>"},{"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.","cause":"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.","error":"ModuleNotFoundError: No module named '<module_name>'"},{"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.","cause":"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.","error":"FileNotFoundError: [Errno 2] No such file or directory: '<file_path>'"},{"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.","cause":"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.","error":"ImportErrorWhenRunningHook: Failed to import module __PyInstaller_hooks_0_<module_name>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"pyinstaller","cli_version":"ERROR: On Linux, objdump is required. It is typically provided by the 'binutils' package installable via your Linux distribution's package manager.","type":"library","homepage":"https://pyinstaller.org","github":"https://github.com/pyinstaller/pyinstaller","docs":"https://pyinstaller.org","changelog":"https://pyinstaller.org/en/stable/CHANGES.html","pypi":"https://pypi.org/project/pyinstaller/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-09","next_check":"2026-07-08","install_tag":null}}