PyInstaller(1)

📦 version 6.22.2, in debian trixie, ubuntu stonking

pyinstaller 💖 bundle a Python app and every single dependency into one little package ✨

okay bestie, sit down, hydrate, because this one is a whole journey 🫶. pyinstaller takes your Python application, grabs all of its dependencies, and squishes them into a single package. iconic behaviour, honestly.

🌸 DESCRIPTION 🌸

here's the whole vibe of how you call it:

usage: pyinstaller [-h] [-v] [-D] [-F] [--specpath DIR] [-n NAME]
[--contents-directory CONTENTS_DIRECTORY] [--add-data SOURCE:DEST]
[--add-binary SOURCE:DEST] [-p DIR] [--hidden-import MODULENAME]
[--collect-submodules MODULENAME] [--collect-data MODULENAME]
[--collect-binaries MODULENAME] [--collect-all MODULENAME]
[--copy-metadata PACKAGENAME] [--recursive-copy-metadata PACKAGENAME]
[--additional-hooks-dir HOOKSPATH] [--runtime-hook RUNTIME_HOOKS]
[--exclude-module EXCLUDES] [--splash IMAGE_FILE] [-d
{all,imports,bootloader,noarchive}] [--optimize LEVEL] [--python-option
PYTHON_OPTION] [-s] [--noupx] [--upx-exclude FILE] [-c] [-w]
[--hide-console {minimize-early,hide-late,minimize-late,hide-early}] [-i
<FILE.ico or FILE.exe,ID or FILE.icns or Image or "NONE">]
[--disable-windowed-traceback] [--version-file FILE] [--manifest <FILE
or XML>] [-m <FILE or XML>] [-r RESOURCE] [--uac-admin] [--uac-uiaccess]
[--argv-emulation] [--osx-bundle-identifier BUNDLE_IDENTIFIER]
[--target-architecture ARCH] [--codesign-identity IDENTITY]
[--osx-entitlements-file FILENAME] [--runtime-tmpdir PATH]
[--bootloader-ignore-signals] [--distpath DIR] [--workpath WORKPATH]
[-y] [--upx-dir UPX_DIR] [--clean] [--log-level LEVEL] scriptname
[scriptname ...]

like… look at all those flags. she's thriving. 💅

🎯 positional arguments 🎯

  • scriptname — the name(s) of the scriptfile(s) you want processed, or exactly one .spec file. heads up: if you hand over a .spec file, most of the options below are unnecessary and just get ignored. this one is required, no skipping it bestie. (required)

⚙️ options ⚙️

  • -h, --help — shows you this help message and dips. bye! 👋
  • -v, --version — shows the program version info and exits.
  • --distpath DIR — where the bundled app goes to live. (default: ./dist)
  • --workpath WORKPATH — where all the temporary work files go — your .log, .pyz, and etc. (default: ./build)
  • -y, --noconfirm — replaces the output directory (default: SPECPATH/dist/SPECNAME) without asking you for confirmation first. no vibe check, just sends it. 🔥
  • --upx-dir UPX_DIR — path to the UPX utility. (default: search the execution path)
  • --clean — cleans the PyInstaller cache and removes temporary files before building. little pre-game reset, love that for her. 🧼
  • --log-level LEVEL — how much detail you get in the build-time console messages. LEVEL can be one of TRACE, DEBUG, INFO, WARN, DEPRECATION, ERROR, FATAL (default: INFO). it's also settable via the PYI_LOG_LEVEL environment variable, and this option overrides that env var. 👑

🎀 What to generate: 🎀

  • -D, --onedir — creates a one-folder bundle that contains an executable. this is the default, she's the main character. 👑
  • -F, --onefile — creates a one-file bundled executable. just one lil file. precious.
  • --specpath DIR — the folder where the generated spec file gets stored. (default: current directory)
  • -n NAME, --name NAME — the name you assign to the bundled app and the spec file. (default: the first script's basename)
  • --contents-directory CONTENTS_DIRECTORY — for onedir builds only, bb. this sets the name of the directory where all the supporting files go — and by "supporting files" we mean literally everything except the executable itself. want the old onedir layout with no contents directory at all? pass "." and it's like the contents directory never happened. 🪄
  • --add-data SOURCE:DEST — extra data files (or whole directories full of data files) to add to the application. the argument value should look like "source:dest_dir", where source is the path to the file (or directory) being collected, and dest_dir is the destination directory relative to the top-level application directory. the two paths are separated by a colon (:). wanna drop a file straight into the top-level application directory? use . as the dest_dir. this option can be used multiple times. 💖
  • --add-binary SOURCE:DEST — extra binary files to add to the executable. peep the --add-data option for the format, it's the same deal. this option can be used multiple times.
  • -p DIR, --paths DIR — a path to search for imports (basically like using PYTHONPATH). multiple paths are allowed, separated by ':', or you can just use this option multiple times. equivalent to supplying the pathex argument in the spec file. 🦋
  • --hidden-import MODULENAME, --hiddenimport MODULENAME — names an import that isn't visible in the code of the script(s). sneaky little import, we see you 👀. this option can be used multiple times.
  • --collect-submodules MODULENAME — collects all submodules from the specified package or module. this option can be used multiple times.
  • --collect-data MODULENAME, --collect-datas MODULENAME — collects all data from the specified package or module. this option can be used multiple times.
  • --collect-binaries MODULENAME — collects all binaries from the specified package or module. this option can be used multiple times.
  • --collect-all MODULENAME — collects all submodules, data files, and binaries from the specified package or module. the full set, the whole package, the entire meal. 🍽️ this option can be used multiple times.
  • --copy-metadata PACKAGENAME — copies metadata for the specified package. this option can be used multiple times.
  • --recursive-copy-metadata PACKAGENAME — copies metadata for the specified package and all of its dependencies. she brings her whole friend group. this option can be used multiple times.
  • --additional-hooks-dir HOOKSPATH — an additional path to search for hooks. this option can be used multiple times.
  • --runtime-hook RUNTIME_HOOKS — path to a custom runtime hook file. a runtime hook is code that gets bundled with the executable and runs before any other code or module, to set up special features of the runtime environment. first in line, always. this option can be used multiple times.
  • --exclude-module EXCLUDES — an optional module or package (and bestie, that's the Python name, not the path name) that will be ignored, as though it was never found in the first place. ghosted. 👻 this option can be used multiple times.
  • --splash IMAGE_FILE — (EXPERIMENTAL) adds a splash screen with the image IMAGE_FILE to the application. the splash screen can display progress updates while unpacking. cute and informative. ✨

🛠️ How to generate: 🛠️

  • -d {all,imports,bootloader,noarchive}, --debug {all,imports,bootloader,noarchive} — gives you a hand with debugging a frozen application. this argument may be provided multiple times to select several of the following options:
    • all: all three of the following options.
    • imports: specifies the -v option to the underlying Python interpreter, which makes it print a message each time a module is initialized, showing the place (filename or built-in module) from which it's loaded. see https://docs.python.org/3/using/cmdline.html#id4.
    • bootloader: tells the bootloader to issue progress messages while initializing and starting the bundled app. used to diagnose problems with missing imports.
    • noarchive: instead of storing all frozen Python source files as an archive inside the resulting executable, stores them as files in the resulting output directory.
  • --optimize LEVEL — the bytecode optimization level used for collected python modules and scripts. for details, see the section "Bytecode Optimization Level" in the PyInstaller manual. 📚
  • --python-option PYTHON_OPTION — specifies a command-line option to pass to the Python interpreter at runtime. currently supports "v" (equivalent to "--debug imports"), "u", "W <warning control>", "X <xoption>", and "hash_seed=<value>". for details, see the section "Specifying Python Interpreter Options" in the PyInstaller manual.
  • -s, --strip — applies a symbol-table strip to the executable and shared libs. not recommended for Windows, so like… read the room. 🫠
  • --noupx — do not use UPX even if it's available. heads up: this works differently between Windows and *nix.
  • --upx-exclude FILE — prevents a binary from being compressed when using upx. typically used when upx corrupts certain binaries during compression (rude of it, honestly). FILE is the filename of the binary without the path. this option can be used multiple times.

🪟 Windows and Mac OS X specific options: 🍎

  • -c, --console, --nowindowed — opens a console window for standard i/o. this is the default. on Windows, this option has no effect if the first script is a .pyw file.
  • -w, --windowed, --noconsole — Windows and Mac OS X: do not provide a console window for standard i/o. on Mac OS this also triggers building a Mac OS .app bundle. on Windows this option is automatically set if the first script is a .pyw file. this option is ignored on *NIX systems. 🐧
  • --hide-console {minimize-early,hide-late,minimize-late,hide-early} — Windows only: in a console-enabled executable, this has the bootloader automatically hide or minimize the console window if the program owns the console window (i.e., it was not launched from an existing console window).
  • -i <FILE.ico or FILE.exe,ID or FILE.icns or Image or "NONE">, --icon <FILE.ico or FILE.exe,ID or FILE.icns or Image or "NONE"> — let's break it down, bestie:
    • FILE.ico: applies the icon to a Windows executable.
    • FILE.exe,ID: extracts the icon with ID from an exe.
    • FILE.icns: applies the icon to the .app bundle on Mac OS.
    • if you enter an image file that isn't in the platform format (ico on Windows, icns on Mac), PyInstaller tries to use Pillow to translate the icon into the correct format (if Pillow is installed).
    • use "NONE" to not apply any icon at all, which makes the OS show some default. (default: apply PyInstaller's icon)
    • this option can be used multiple times. 💅
  • --disable-windowed-traceback — disables the traceback dump of unhandled exception in windowed (noconsole) mode (Windows and macOS only), and instead displays a message that this feature is disabled.

🪟 Windows specific options: 🪟

  • --version-file FILE — adds a version resource from FILE to the exe.
  • --manifest <FILE or XML> — adds manifest FILE or XML to the exe.
  • -m <FILE or XML> — Deprecated shorthand for --manifest. it's giving legacy, use the long one.
  • -r RESOURCE, --resource RESOURCE — bestie, this one adds or updates a resource inside a Windows executable. RESOURCE is one to four items, and they go like this: FILE[,TYPE[,NAME[,LANGUAGE]]]. The FILE can be a data file, or it can be an exe/dll. If it's a data file, you gotta give at least TYPE and NAME — no skipping. LANGUAGE defaults to 0, or you can throw a wildcard * in there to update, like, all the resources of that given TYPE and NAME. Now if FILE is an exe/dll, then every resource from FILE gets added/updated into the final executable as long as TYPE, NAME and LANGUAGE are omitted or set to wildcard *. And yeah, you can use this option more than once. Go off. 💅
  • --uac-admin — flip this on and you get a Manifest that will request elevation the moment the app starts. UAC popup, here we come. 🔥
  • --uac-uiaccess — this one lets an elevated application play nice with Remote Desktop. Teamwork, honestly.

🍎 Mac OS specific options 🍎

  • --argv-emulation — turns on argv emulation for macOS app bundles. When it's enabled, that very first open-document/URL event gets processed by the bootloader, and the file paths or URLs that come with it get appended to sys.argv. Cute, right? 🦋
  • --osx-bundle-identifier BUNDLE_IDENTIFIER — the macOS .app bundle identifier, which gets used as the default unique program name for code signing purposes. The usual form is a hierarchical name in reverse DNS notation. Example, because examples slay:
com.mycompany.department.appname
Default here is the first script's basename, bestie. Don't forget. ✨
  • --target-architecture ARCH, --target-arch ARCH — the target architecture, macOS only, and the valid values are exactly x86_64, arm64, and universal2. This is what lets you switch between the universal2 version and the single-arch version of your frozen application — provided your Python installation actually supports the target architecture, okay? And if you don't specify a target architecture at all, then the current running architecture is what gets targeted. Periodt. 💜
  • --codesign-identity IDENTITY — the code signing identity (macOS only). Use the identity you pass in to sign the collected binaries and the generated executable. If you don't provide a signing identity? Then adhoc signing is what happens instead. It's giving fallback. 🎀
  • --osx-entitlements-file FILENAME — the entitlements file to use when code-signing the collected binaries (macOS only). That's it, that's the whole vibe. 🌸

🌈 Rarely used special options 🌈

These are the deep-lore options. You probably don't need them. But if you do, you really do. 🙈
  • --runtime-tmpdir PATH — where to extract libraries and support files when you're in onefile mode. If you pass this, the bootloader will ignore any temp-folder location that the run-time OS defined, and the _MEIxxxxxx-folder gets created right here instead. Please only use this option if you know what you are doing — for real, no cap.
Heads up bestie: on POSIX systems, PyInstaller's bootloader does NOT perform shell-style environment variable expansion on the given path string. So using environment variables (like ~ or $HOME) in the path will NOT work. It's giving literally no expansion. 💀
  • --bootloader-ignore-signals — tells the bootloader to ignore signals instead of forwarding them to the child process. Super useful in situations where, say, a supervisor process signals both the bootloader and the child (like via a process group) — this way you avoid signalling the child twice. Main character anti-double-signal energy. 👑

And that's a wrap on the options, bestie — you made it to the end and honestly? Iconic behavior. 🫶

This whole page is from PyInstaller version 6.10.0, dated October 2024, and it lives in the manual as PyInstaller(1). Now go freeze something and slay. 💖✨

📦 where this page comes from