PYI-MAKESPEC(1)

💖 pyi-makespec 💖

okay so bestie, welcome to the PyInstaller Make Spec(1) manual page, and honestly? it's kind of iconic. pyi-makespec is the chill, low-key sibling of pyinstaller: it doesn't build anything, it just writes you a spec file, which is the ✨ recipe ✨ that pyinstaller later turns into a real executable. think of it as the group-chat plan before the actual hangout. 🫶

📛 NAME 📛

pyi-makespec — Make a PyInstaller spec file

🎀 DESCRIPTION 🎀

here's the whole usage vibe, verbatim, no edits, because we do not mess with the facts:

usage: pyi-makespec [-h] [-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] [--log-level LEVEL] scriptname [scriptname
       ...]

so many flags, I know, but every single one is here and accounted for, no cap. let's go. 💅

---

🧍 positional arguments 🧍

• scriptname — the name(s) of the scriptfiles you want processed, or exactly one .spec file. if you hand it a .spec file, most of the options below are unnecessary and just get ignored (rude of them, honestly). this one is required — you can't skip it. 🚨

⚙️ options ⚙️

• -h, --help — shows this help message and dips. classic. 👋
• --log-level LEVEL — how much detail you want in your build-time console messages. LEVEL can be one of TRACE, DEBUG, INFO, WARN, DEPRECATION, ERROR, FATAL (default: INFO). it's also settable via — and overrides — the PYI_LOG_LEVEL environment variable. so many options, so much power. 🌈

✨ What to generate ✨

• -D, --onedir — makes a one-folder bundle that contains an executable. this is the default, so if you say nothing you get this vibe. 🗂️
• -F, --onefile — makes a one-file bundled executable. one file. that's it. that's the whole thing. 🎁
• --specpath DIR — the folder where the generated spec file gets stored (default: the current directory). 🏠
• -n NAME, --name NAME — the name you assign to the bundled app and the spec file (default: the first script's basename). name her, bestie. ✨
• --contents-directory CONTENTS_DIRECTORY — for onedir builds only: the name of the directory where all the supporting files go (i.e. literally everything except the executable itself). use . to re-enable the old onedir layout with no contents directory at all — a little retro moment. 🕰️

🔍 What to bundle, where to search 🔍

• --add-data SOURCE:DEST — extra data files, or directories full of data files, that you want added to the application. the argument value goes in the form "source:dest_dir", where source is the path to the file (or directory) being collected, dest_dir is the destination directory relative to the top-level application directory, and the two paths are separated by a colon (:). to 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 added to the executable. same format as the --add-data option above, iykyk. 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 just use this option multiple times instead. 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 imports deserve love too. 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 — the whole shebang: collects all submodules, data files, and binaries from the specified package or module. this option can be used multiple times. 👑
• --copy-metadata PACKAGENAME — copies the metadata for the specified package. this option can be used multiple times. 📋
• --recursive-copy-metadata PACKAGENAME — copies metadata for the specified package and all its dependencies. this option can be used multiple times. 🌳
• --additional-hooks-dir HOOKSPATH — an extra path to search for hooks. this option can be used multiple times. 🪝
• --runtime-hook RUNTIME_HOOKS — the path to a custom runtime hook file. a runtime hook is code that's bundled with the executable and runs before any other code or module, so it can set up special features of the runtime environment. this option can be used multiple times. ⏰
• --exclude-module EXCLUDES — an optional module or package (the Python name, not the path name) that gets ignored, as though it was never found in the first place. 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 functional. 🌸

🛠️ How to generate 🛠️

• -d {all,imports,bootloader,noarchive}, --debug {all,imports,bootloader,noarchive} — provides assistance with debugging a frozen application. this argument may be provided multiple times so you can 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 every time a module is initialized, showing the place (filename or built-in module) it was loaded from. 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. use this to diagnose problems with missing imports.
  • noarchive: instead of storing all the 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 the 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 the 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 heads up. ✂️
• --noupx — do not use UPX even if it's available. it works differently between Windows and *nix, because of course it does. 🚫
• --upx-exclude FILE — prevents a binary from being compressed when using upx. this is typically used when upx corrupts certain binaries during compression. 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: don't 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 makes 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). sneaky. 🤫
• -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"> — icon time:
  • 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 instead (default: apply PyInstaller's icon). this option can be used multiple times. 🎨

• --disable-windowed-traceback — disables the traceback dump of an 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. 👵
• -r RESOURCE, --resource RESOURCE — adds or updates a resource in a Windows executable. the RESOURCE is one to four items: FILE[,TYPE[,NAME[,LANGUAGE]]]. FILE can be a data file or an exe/dll. for data files, at least TYPE and NAME must be specified. LANGUAGE defaults to 0, or it may be specified as the wildcard * to update all resources of the given TYPE and NAME. for exe/dll files, all resources from FILE will be added/updated to the final executable if TYPE, NAME and LANGUAGE are omitted or specified as the wildcard *. this option can be used multiple times. 🧩
• --uac-admin — using this option creates a Manifest that will request elevation upon application start. big boss energy. 👑
• --uac-uiaccess — using this option allows an elevated application to work with Remote Desktop. 🖱️

🍎 Mac OS specific options 🍎

• --argv-emulation — enables argv emulation for macOS app bundles. if enabled, the initial open document/URL event is processed by the bootloader, and the passed file paths or URLs are appended to sys.argv. 🌟
• --osx-bundle-identifier BUNDLE_IDENTIFIER — okay so this one's the Mac OS .app bundle identifier, and it doubles as the default unique program name when you're doing code signing. The usual shape is a hierarchical name written backwards like DNS, for example: com.mycompany.department.appname (default: the basename of the first script). reverse-DNS girlies rise up 💅
• --target-architecture ARCH, --target-arch ARCH — pick your target architecture (macOS only; the valid values are exactly x86_64, arm64, universal2). This is what lets you flip between the universal2 build and a single-arch build of your frozen app, provided your Python installation actually supports the target architecture. And if you don't specify one at all? Then it just targets whatever architecture is currently running. no notes, it just knows 🦋
• --codesign-identity IDENTITY — your code signing identity (macOS only). Hand it over and it'll be used to sign the collected binaries and the generated executable. Don't provide one? Then it does adhoc signing instead. it's giving "we'll figure it out" energy ✨
• --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 🦄

bestie these are the deep lore options. they're here, they work, but they're not your everyday thing. proceed with main-character-level confidence and also caution 💖

• --runtime-tmpdir PATH — tells it 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 here instead.

🚨 Please use this option only if you know what you are doing. Not me warning you twice, the manpage is warning you twice. this is a "you better know what you're doing" moment fr fr

Also, heads up, and this is the part that gets people: on POSIX systems, PyInstaller's bootloader does NOT perform shell-style environment variable expansion on the path string you give it. So using environment variables in the path — things like ~ or $HOME — will NOT work. it simply will not slay 😭

• --bootloader-ignore-signals — tells the bootloader to ignore signals instead of forwarding them along to the child process. When is this useful? Think of a supervisor process that signals both the bootloader and the child (like, say, via a process group) — this stops the child from getting signalled twice. one signal, one girlie, no doubles 🎀

---

and that's a wrap on the page, bestie 🫶 this one's version 6.10.0, dated October 2024, and it lives in the PyInstaller Make Spec(1) section of your manual. go forth and build something iconic 👑💜