PyInstaller is a tool that packages Python applications and all their dependencies into a single executable file. Users can run the packaged application without needing to install a Python interpreter or any modules.

Normally when executing Python scripts, we need a Python environment and must pre-install all required modules. This can cause inconvenience when sharing scripts with non-technical users. By bundling the program along with the Python environment and all runtime dependencies into a single executable file, program distribution becomes much easier. To some extent, this also helps protect the source code from being exposed.

PyInstaller Usage

pyinstaller.exe command syntax:

pyinstaller [options] scriptfile [scriptfile …] | specfile

Only common options for Windows systems are listed below. For complete documentation, please refer to:

Positional Arguments

  • scriptfile Python script file to process
  • specfile .spec file

Common Options

  • -h,--help Show help message and exit
  • -v,--version Show program version and exit
  • --distpath DIR Output directory for bundled application (default: ./dist)
  • --workpath WORKPATH Temporary directory (default: ./build)
  • --clean Clean PyInstaller cache and remove temporary files before building
  • --log-level LEVEL Level of detail for build-time console messages

    LEVEL may be one of TRACE, DEBUG, INFO, WARN, DEPRECATION, ERROR, FATAL (default: INFO).

  • -D， --onedir Create one-folder bundle containing executable (default)
  • -F, --onefile Create one-file bundled executable
  • --specpath DIR Folder to store generated spec file (default: current directory)
  • -n, --name NAME Name for bundled application and spec file (default: first script's name)
  • --add-data SOURCE:DEST Additional non-binary files to include in the application
  • --add-binary SOURCE:DEST Additional binary files to include in the executable

    Similar to --add-data option. This option can be used multiple times;

  • -p, --paths DIR Path to search for imports

    Multiple paths allowed, separated by : or use this option multiple times;

  • --hidden-import, --hiddenimport MODULENAME Name an import not visible in the code
  • --collect-submodules MODULENAME Collect all submodules from the specified package or module
  • --collect-data, --collect-datas MODULENAME Collect all data from the specified package or module
  • --collect-binaries MODULENAME Collect all binaries from the specified package or module
  • --collect-all MODULENAME Collect all submodules, data files and binaries from the specified package or module
  • --exclude-module EXCLUDES Exclude module or package
  • --splash IMAGE_FILE Add splash screen with image IMAGE_FILE

    The splash screen can display progress during unpacking;

  • -c, --console, --nowindowed Open console window (default)
  • -w, --windowed, --noconsole Do not provide console window
  • -i, --icon <FILE.ico or FILE.exe,ID or Image or "NONE">

    Add icon to Windows executable (default: PyInstaller's icon);

    • FILE.ico: Apply icon to Windows executable
    • FILE.exe,ID: Extract icon with specified ID from exe file
    • Image: If input image isn't in ico format, PyInstaller will attempt conversion using Pillow (if installed)
    • NONE: Don't add any icon
  • --version-file FILE Add version resource from FILE to exe
  • --manifest <FILE or XML> Add manifest file to exe

Common Examples

Package myscript.py into a single exe file without an icon:

pyinstaller -F -i NONE d:\myscript.py