pyfuze: Package Python Projects into Standalone Executables

Introduction

pyfuze is an innovative open-source tool that simplifies the process of transforming your Python projects into standalone executables. Built upon the robust foundations of cosmopolitan and uv, pyfuze addresses the common challenge of distributing Python applications by bundling all necessary dependencies and the Python interpreter itself into a single file. It offers three distinct packaging modes, each tailored for specific requirements regarding offline capability, cross-platform compatibility, and package size.

Installation

Getting started with pyfuze is straightforward. You can install it directly using pip:

pip install pyfuze

Alternatively, you can run it directly with uvx:

uvx pyfuze -h

Examples

pyfuze provides flexible options to package your Python applications, adapting to different project structures and deployment scenarios. Here are some common use cases:

Portable Mode

The portable mode is ideal for generating a standalone, cross-platform executable, particularly well-suited for simpler scripts. It requires no extraction or internet connection at runtime.

pyfuze ./examples/simple.py --mode portable --reqs requests

Bundle Mode

For more complex projects, the bundle mode packages your application with Python and all its dependencies. This example demonstrates packaging a folder-based project, specifying the entry file, including pyproject.toml and uv.lock for dependency management, and adding extra files while excluding others. The --win-gui option is perfect for GUI applications on Windows.

pyfuze ./examples/complex \
  --entry app.py \
  --pyproject ./examples/complex/pyproject.toml \
  --uv-lock ./examples/complex/uv.lock \
  --include ./examples/complex/config.txt \
  --exclude ./examples/complex/build.py \
  --unzip-path complex \
  --win-gui

Online Mode

The online mode creates a smaller, cross-platform package. It requires an internet connection at runtime to download Python and dependencies. This mode can be configured with mirror URLs for improved reliability in restricted network environments.

pyfuze ./examples/complex \
  --entry app.py \
  --pyproject ./examples/complex/pyproject.toml \
  --uv-lock ./examples/complex/uv.lock \
  --include ./examples/complex/config.txt \
  --exclude ./examples/complex/build.py \
  --unzip-path complex \
  --win-gui \
  --mode online \
  --uv-install-script-windows <uv-windows-installer-mirror-url> \
  --uv-install-script-unix <uv-unix-installer-mirror-url> \
  --env INSTALLER_DOWNLOAD_URL=<uv-binary-mirror-url> \
  --env UV_PYTHON_INSTALL_MIRROR=<python-install-mirror-url> \
  --env UV_DEFAULT_INDEX=<pypi-mirror-url>

Why use pyfuze?

pyfuze offers a compelling solution for Python developers looking to simplify application distribution. Its key advantages include:

Simplified Distribution: Package your entire Python application, including the interpreter and all dependencies, into a single executable, eliminating the need for users to install Python or manage virtual environments.
Flexible Packaging Modes: Choose between 'bundle' for maximum compatibility on a single platform, 'online' for smaller cross-platform packages with runtime downloads, or 'portable' for truly standalone, pure Python cross-platform executables.
Cross-Platform Support: With 'online' and 'portable' modes, pyfuze enables your applications to run on macOS (ARM64 and AMD64), Linux (AMD64), and Windows (AMD64).
Leverages Modern Tools: Built on cosmopolitan and uv, pyfuze benefits from efficient dependency resolution and robust executable creation.
Ease of Use: A straightforward command-line interface makes packaging your projects quick and efficient.

Links

Explore pyfuze further using these official resources: