# PyInstaller — Freeze Python Apps into Standalone Executables

> Bundle a Python application and all its dependencies into a single distributable package for Windows, macOS, and Linux.

## Install

Save in your project root:

# PyInstaller — Freeze Python Apps into Standalone Executables

## Quick Use
```bash
pip install pyinstaller
# create a one-file executable:
pyinstaller --onefile my_app.py
# output lands in dist/my_app
./dist/my_app
```

## 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/

---
Source: https://tokrepo.com/en/workflows/68c777da-4211-11f1-9bc6-00163e2b0d79
Author: AI Open Source