PyOxidizer — Package Python Apps as Standalone Executables

Introduction

PyOxidizer solves a longstanding Python distribution problem: getting your application onto a user's machine without requiring them to install Python or manage virtual environments. It embeds a fully functional Python interpreter, your code, and all dependencies into a single executable file. The result is a binary that runs anywhere the target OS runs, with no external dependencies.

What PyOxidizer Does

• Embeds a Python interpreter and all Python modules into a single native executable
• Loads Python modules from memory instead of the filesystem for faster startup
• Supports packaging for Windows, macOS, and Linux from a single configuration file
• Handles C extensions by linking them statically into the binary
• Produces distributable artifacts including executables, installers, and macOS app bundles

Architecture Overview

PyOxidizer uses a Rust-based build system that compiles a custom Python interpreter (based on CPython) with your application code baked in. The configuration is written in Starlark (a Python-like language). During the build, PyOxidizer resolves your Python dependencies, collects bytecode-compiled modules, and links everything into a Rust binary using the oxidized-importer — a custom import mechanism that reads Python modules from in-memory data structures rather than the filesystem. This approach eliminates filesystem I/O during module imports, resulting in faster cold starts compared to traditional Python deployments.

Self-Hosting & Configuration

• Install Rust and then cargo install pyoxidizer, or grab a pre-built binary from GitHub Releases
• Run pyoxidizer init-config-file to generate a pyoxidizer.bzl configuration file
• Specify Python packages to include using pip_install() directives in the config
• Set the target triple (e.g., x86_64-unknown-linux-gnu) for cross-platform builds
• Use pyoxidizer build --release for optimized production binaries

Key Features

• Single-file executables with no Python installation required on the target machine
• In-memory module loading eliminates filesystem overhead for faster application startup
• Starlark-based configuration language provides programmatic control over the build process
• Cross-compilation support for building Linux binaries on macOS and vice versa
• Integrates with pip so existing requirements.txt and setup.py projects work without modification

Comparison with Similar Tools

• PyInstaller — bundles Python into a directory or one-file archive that extracts at runtime; PyOxidizer embeds everything in a true native binary
• Nuitka — compiles Python to C and produces optimized executables; PyOxidizer embeds CPython without transpilation
• cx_Freeze — creates frozen executables but still requires a runtime directory; PyOxidizer produces a single file
• Briefcase (BeeWare) — focuses on GUI app packaging with platform-native installers; PyOxidizer targets any Python application
• Shiv / PEX — creates self-contained zipapps that still require a system Python; PyOxidizer bundles the interpreter itself

FAQ

Q: Does PyOxidizer work with C extensions like NumPy? A: Yes, but C extensions must be compiled and linked statically. Some complex extensions may require additional configuration.

Q: How large are the produced binaries? A: A minimal application produces binaries around 20-30 MB, which includes the embedded Python interpreter and standard library.

Q: Can I use PyOxidizer with virtual environments? A: PyOxidizer replaces the need for virtual environments by embedding all dependencies directly. You specify packages in the config file instead.

Q: Is PyOxidizer suitable for production use? A: PyOxidizer is used in production for distributing CLI tools and internal applications. Test your specific use case thoroughly, especially with complex C extensions.

Sources

• https://github.com/indygreg/PyOxidizer
• https://pyoxidizer.readthedocs.io/