pyappdist

Build native installers for Python apps without hunting down hidden imports, data files, or plugins.

Warning

Alpha. pyappdist is under active development. It works end-to-end today, but the config schema, CLI, and output layout may still change without notice.

pyappdist does not freeze your code. Instead of bundling Python and your app into a single executable (and fighting hidden imports, data files, and plugins along the way), it installs your app into a real, dedicated Python runtime — exactly the way pip would — and ships that.

Because the runtime is a normal Python environment, most apps run as-is: no hooks, no --hidden-import, no --add-data, no per-library workarounds. If it runs under uv run, it almost certainly runs after pyappdist build.

Shipping a full runtime without selecting files makes packages larger, but against modern storage sizes that is a favorable trade for an environment that just runs.

Output formats

One pyproject.toml can describe several output packages at once — each is a target with its own platform and format:

msi

windows-x86_64 → .msi installer.

msix

windows-x86_64 → .msix (Store / sideloading).

linux

linux-x86_64 → .run installer.

macos

macos-aarch64 → .run installer, for command-line tools.

macapp / dmg

macos-aarch64 → a signed/notarized .app bundle, optionally inside a .dmg, for GUI apps.

image

any platform → a .zip / .tar.gz of the image tree, with no installer.

Why “just works”

Freezers reconstruct your app by static analysis, so anything dynamic tends to break and needs manual patching. pyappdist skips all of that:

• Real install layout — dist-info, entry points, .pth files, and package data are exactly where the package authors put them. importlib.metadata / importlib.resources behave identically to a normal install.

• Real binary wheels — C extensions and platform wheels (incl. abi3) are installed unmodified, with the real interpreter and DLL search paths. No bundling guesswork.

• Real GUI stacks — Qt plugins ship in PySide6’s normal wheel layout; matplotlib’s TkAgg backend uses the runtime’s bundled tkinter. They just load.

On Windows the launcher is a tiny C stub that starts the bundled python.exe / pythonw.exe as a subprocess, so there is no pythonXX.dll embedding and no C-API version risk — the stub never changes when the Python version does. The macOS .app uses an equivalent compiled Mach-O stub; Linux and the macOS .run use a relocatable shell wrapper. See How it works.

Getting started

• Installation
  • Build-time toolchain
  • Package manager (for dependency pinning)
• Tutorial: installers from scratch
  • Step 1 — Scaffold a package with uv
  • Step 2 — Write the tkinter “hello world”
  • Step 3 — Test that the project builds a wheel
  • Step 4 — Test the launcher command from the installed wheel
  • Step 5 — Add the pyappdist configuration
  • Step 6 — Build the installer
  • Step 7 — Confirm the upgrade-code
  • Step 8 — Add a Linux .run installer
  • Step 9 — Add a macOS .dmg
  • Where to go next

Concepts

• How it works
  • What your project must satisfy
  • The pipeline
  • The launcher
  • GUI startup errors (Windows)
• Dependency resolution
  • Why the lockfile
  • Why the target interpreter
  • Manager detection
  • Per-package indexes (uv only)
  • Including optional-dependency extras
  • Overriding the manager
  • requirements.txt mode
  • Fallback behavior

Shipping guides

• Windows — MSI installer
  • Build requirements
  • Configuration
  • Install behavior
  • Upgrades
  • Code signing
• Windows — MSIX (Microsoft Store / sideloading)
  • Build requirements
  • Configuration
  • Signing and install
• Linux — .run installer
  • Build requirements
  • Configuration
  • Install behavior
• macOS — .run installer (command-line tools)
  • Build requirements
  • Configuration
  • Install behavior
• macOS — .app / .dmg (GUI apps)
  • Build requirements
  • Configuration
  • Code signing and notarization
  • Install behavior
• Image archive (all platforms)
  • Build requirements
  • Configuration
  • Run behavior

Reference

• Configuration
  • All keys at a glance
  • [tool.pyappdist]
  • [[tool.pyappdist.launchers]]
  • [[tool.pyappdist.targets]]
• Command-line interface
  • Common options
  • Output layout
  • Commands
  • Examples
• Samples
  • CLI samples
  • GUI samples
• Release history
  • 0.10.0
  • 0.9.0
  • 0.8.0
  • 0.7.0
  • 0.6.0
  • 0.5.0
  • 0.4.0
  • 0.3.1
  • 0.3.0
  • 0.2.0
• GitHub

Status

Alpha — the pipeline works end-to-end, but expect breaking changes to the config schema, CLI, and output layout as it matures.

Targets today are Windows x64 (msi, msix), Linux x64 (linux), and macOS arm64/x64 (macos, macapp, dmg). Auto-update and code-signing certificates are out of scope for now; optional code signing of the Windows artifacts is available. Distributed apps are not obfuscated, and unsigned Windows installers will trigger a SmartScreen warning.