Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 38 ยท Distribution and Docker

Zipapps and Standalone Executables

Distribute Python command-line apps without asking users to set up environments. Build a real zipapp, learn entry points, pipx, uv tool, shiv, pex and PyInstaller.

Not everyone who wants to use your tool is a Python developer. A system administrator wants one file to copy to a server. A teammate wants to type a command and have it work. A customer on Windows does not have Python at all. This lesson covers the distribution options between "publish to PyPI" and "ship a Docker image": entry points, tool installers, zipapps and frozen executables.

Building a zipapp works inside this page, so you will create and run one for real. Tools that need an operating system shell (PyInstaller, pipx) are shown read-only.

Level 1: a command on the PATH (entry points)

The best experience for most Python users is a normal command name. You declare it in pyproject.toml:

TOML
[project.scripts]
greet = "myapp.cli:main"

This means: when the package is installed, create an executable named greet that imports main from the module myapp.cli and calls it. Installers generate a small launcher script (greet.exe on Windows) for each entry. A GUI application uses [project.gui-scripts].

The resolution of "module:function" is simple enough to implement in a few lines:

Python How an entry point launcher works

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The generated launcher also calls sys.exit(...) with the return value, so your function's return value becomes the process exit status.

Level 2: tool installers

Users should not pip install command-line tools into whatever environment is active. Two installers give each tool its own isolated environment and put its commands on the PATH:

Terminal
pipx install myapp              # pipx: one venv per tool
pipx run myapp                  # run once without installing

uv tool install myapp           # uv's equivalent
uvx myapp --help                # run a tool in a temporary environment

Document these commands in your README. They fix the two most common support problems at once: dependency conflicts and "command not found".

Level 3: zipapps, a single runnable file

A zipapp is a ZIP archive containing Python code and a __main__.py, with an optional shebang line so Unix systems can execute it directly. Python can run any such archive: python app.pyz. The standard library module zipapp builds them, and everything below is real Python:

Python Build and run a zipapp

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first line of the archive is the shebang (#!/usr/bin/env python3); after it the ZIP data begins. On Linux and macOS you can make the file executable (chmod +x textstats.pyz) and run it as ./textstats.pyz. On Windows, python textstats.pyz works, and the Python launcher can associate .pyz files.

Command-line equivalent:

Terminal
python -m zipapp src -o textstats.pyz -p "/usr/bin/env python3"
python -m zipapp src -o textstats.pyz -m "textstats.cli:main"   # generate __main__ for you

What a plain zipapp cannot do

  • It does not bundle dependencies by itself. Install them into the folder first with pip install -r requirements.txt --target src/, then archive.
  • Packages with compiled extensions (NumPy, for example) cannot be imported from inside a ZIP, and files that must exist on disk (data files, __file__ paths) are awkward. Use importlib.resources instead of file paths for data.
  • The user still needs a compatible Python interpreter.

Tools built on the same idea fix some of this. shiv and pex create zipapp-like files that include dependencies and unpack extensions to a cache on first run. They are popular for deploying internal tools to servers that already have Python:

Terminal
shiv -c greet -o greet.pyz .          # build from the current project
pex . -c greet -o greet.pex

Level 4: frozen executables

When users have no Python, you bundle the interpreter itself. PyInstaller, Nuitka, cx_Freeze and py2app (macOS) produce a folder or single file that runs without a Python installation:

Terminal
pip install pyinstaller
pyinstaller --onefile --name greet src/myapp/cli.py
# result: dist/greet (or dist/greet.exe)
Tool How it works Notes
PyInstaller Collects your code, the interpreter and libraries into a bundle Most popular; one build per OS
Nuitka Translates Python to C and compiles Can be faster; longer builds
cx_Freeze Bundles into a folder, can make installers Similar idea
Briefcase Packages GUI apps for each platform Part of BeeWare

Practical points:

  • Build on each target OS (and CPU architecture). A Windows executable cannot be built on Linux without extra tooling. A CI matrix is the usual answer.
  • The files are large (tens of megabytes) because they include a whole interpreter.
  • Dynamic imports and data files sometimes need hints (--hidden-import, --add-data).
  • Antivirus programs sometimes flag unsigned one-file executables. Code signing (and notarization on macOS) is part of real-world distribution.
  • Always test the frozen program on a machine without Python installed.

Choose the lightest option that fits your audience. Developers: PyPI plus pipx or uv tool. Servers with Python: a zipapp or pex. Customers without Python: a frozen executable or an installer. Services: a Docker image.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does greet = "myapp.cli:main" under [project.scripts] create?

    Installers generate a launcher for each entry; it imports the module and calls the named function.
  2. 2. What must a zipapp contain to be runnable?

    Python executes __main__.py from the archive root when you run python app.pyz.
  3. 3. Why can a plain zipapp fail for a project that uses NumPy?

    Native extensions must be loaded from real files on disk. Tools like shiv and pex unpack them to a cache.
  4. 4. A customer has no Python installed. Which option fits best?

    Frozen executables include the interpreter. They must be built per operating system and architecture.

Summary

  • Declare commands with [project.scripts]; installers generate the launchers.
  • pipx and uv tool install command-line apps in isolated environments.
  • A zipapp is one runnable .pyz file built with the standard zipapp module; it still needs Python and pure-Python dependencies.
  • shiv and pex bundle dependencies; PyInstaller, Nuitka and cx_Freeze bundle the interpreter too, one build per operating system.
  • Pick the lightest distribution method your users can handle.

Next: Private Indexes, Mirrors and Vendoring