PyInstaller — Freeze Python Apps into Standalone Executables

Introduction

PyInstaller analyzes a Python script, collects every module and library it imports, and bundles them together with a Python interpreter into a self-contained folder or single executable. End users never need to install Python or any packages.

What PyInstaller Does

• Traces all imports (including hidden ones) to build a complete dependency graph
• Bundles the CPython interpreter, bytecode, and shared libraries into a dist folder
• Produces single-file executables via the --onefile flag using an embedded archive
• Supports Windows, macOS, and Linux from a single spec-file workflow
• Handles data files, icons, version info, and code-signing metadata

Architecture Overview

PyInstaller runs a recursive import analysis starting from your entry script, building a table of every module, C extension, and data file required. It copies these into a staging directory alongside a bootloader binary written in C. The bootloader unpacks or maps the archive at runtime and initializes the embedded Python interpreter. A .spec file gives you full control over the bundling process.

Self-Hosting & Configuration

• Install via pip: pip install pyinstaller
• Use --onedir (default) for a folder bundle or --onefile for a single binary
• Edit the generated .spec file to add data files, hidden imports, or runtime hooks
• Set --windowed on Windows/macOS to suppress the console window for GUI apps
• Use --add-data and --add-binary flags to include non-Python resources

Key Features

• Zero runtime dependency — users do not need Python installed
• Automatic hidden-import detection for most popular libraries
• Cross-platform output from the same spec file (build on each target OS)
• Hook system with community-maintained hooks for 500+ packages
• Compatible with virtualenvs and conda environments

Comparison with Similar Tools

• Nuitka — compiles Python to C for native speed; PyInstaller bundles bytecode without compilation
• cx_Freeze — similar freeze approach but smaller hook ecosystem
• py2exe — Windows-only; less actively maintained
• Briefcase (BeeWare) — targets mobile and desktop app packaging with native installers
• Shiv — creates self-contained Python zipapps but still requires a Python interpreter on the target

FAQ

Q: Does PyInstaller cross-compile for other operating systems? A: No. You must build on the target OS. Use CI services to produce binaries for each platform.

Q: My app fails with a missing module error after bundling. How do I fix it? A: Add the module to --hidden-import on the command line or in the spec file. Some dynamic imports are not detected automatically.

Q: Can I bundle a GUI application? A: Yes. PyInstaller supports Tkinter, PyQt, PySide, wxPython, and Kivy. Use --windowed to hide the console.

Q: How large are the output binaries? A: Size depends on included libraries. A minimal script produces a 10-15 MB binary; data-science stacks can reach 200 MB+.

Sources

• https://github.com/pyinstaller/pyinstaller
• https://pyinstaller.org/en/stable/