Build a Python .exe with uv and PyInstaller (Tested)

PyInstaller bundles whatever's in the current environment. The classic failure is an .exe that crashes with ModuleNotFoundError because a dependency wasn't installed where PyInstaller looked. uv removes that whole class of problem: it owns the project's Python and its dependencies, so uv run pyinstaller builds against *exactly* the packages your app declares — and a uv.lock makes it reproducible for anyone who checks out the repo.

• One environment — Python, your deps, and PyInstaller all managed by uv; no manual venv activation.
• Reproducible — uv.lock pins exact versions, so the build isn't a 'works on my machine' artifact.
• Fast — dependency resolution and installs are near-instant.
• Third-party packages bundle correctly — the reason to leave the browser: our online builder is standard-library-only, this handles rich, requests, numpy, anything.

Create the project — uv will fetch the Python version you name if you don't have it — then add a real dependency. Here we use rich so the build has something non-stdlib to bundle:

# 1. create the project (uv picks/downloads the Python for you)
uv init greeter --python 3.12
cd greeter

# 2. add a real runtime dependency
uv add rich

uv add rich resolved and installed rich 15.0.0 (plus its own deps markdown-it-py, mdurl, pygments) in a few hundred milliseconds, wrote rich>=15.0.0 into pyproject.toml, and pinned exact versions in uv.lock. Now a small program that uses it:

import sys
from rich.console import Console
from rich.panel import Panel

def main():
    console = Console()
    name = sys.argv[1] if len(sys.argv) > 1 else "world"
    console.print(Panel(f"Hello, {name}!", title="greeter", border_style="green"))

if __name__ == "__main__":
    main()

Add PyInstaller as a dev-only dependency, then build. Because uv run executes inside the project's environment, PyInstaller sees rich and bundles it automatically:

# PyInstaller as a dev-only dependency
uv add --dev pyinstaller

# build: uv runs PyInstaller inside the project env, so it sees rich
uv run pyinstaller --onefile --name greeter app.py

The one-file binary lands in dist/. In my run (uv 0.12.1, PyInstaller 6.22.2) this produced dist/greeter.exe at 11.3 MB — bigger than a standard-library-only build because rich, pygments and markdown-it-py are bundled in. Prefer not to add PyInstaller to the project at all? uvx runs it one-shot:

uvx pyinstaller --onefile --name greeter app.py

The whole point is a single file that runs on a machine with no Python and no pip install. Running the built binary shows rich working from inside the bundle:

> .\dist\greeter.exe Acme
+---------------------------------- greeter ----------------------------------+
| Hello, Acme!                                                               |
+-----------------------------------------------------------------------------+

That box is drawn by rich — a third-party package — running from inside the standalone .exe. No interpreter, no dependencies installed on the target machine.

uv add writes a uv.lock (162 lines for this tiny project) that pins every transitive dependency to an exact version and hash. Commit it, and anyone can reproduce your build exactly:

uv sync            # install the exact locked versions
uv run pyinstaller --onefile --name greeter app.py

This is the difference between a build that happens to work today and one that still builds identically in six months or on a CI runner — the dependency versions can't drift underneath you.

PyInstaller cannot cross-compile: run it on the OS you're targeting — Windows for a .exe, macOS for an app bundle, Linux for an ELF binary. The uv workflow above works on all three; just run it on each machine (or each CI runner).

So which route should you use?

• `ModuleNotFoundError` at runtime — PyInstaller missed a dynamically imported module. Add it with --hidden-import <module>. Building with uv already prevents the most common cause (the dependency not being installed at all).
• Missing data files — bundle them with --add-data "src;dest" (PyInstaller 6+ accepts a : separator on every platform).
• Big executables — a onefile build bundles the interpreter and every dependency, so pulling in rich took the binary to 11.3 MB. Use --onedir for faster startup, or trim unused dependencies.
• Windows SmartScreen warning on the finished .exe — expected for any new, unsigned download; see the explanation and fixes on our Python-to-EXE guide.