uv-trampoline-builder

crates/uv-trampoline-builder/ produces the small Windows executables that act as console shims for venv-installed scripts. It embeds prebuilt binaries from crates/uv-trampoline/ (a nightly-only no_std crate) and stamps them with the right paths at install time.

Purpose

On Windows, putting a Python script directly into Scripts/ doesn't work the way it does on Unix — there's no #! honoring. The standard approach is a tiny .exe that re-launches the venv's Python and invokes the actual entry point. uv adopts that approach with its own trampoline implementation derived from Posy's posy-trampoline.

Directory layout

crates/uv-trampoline-builder/src/
├── lib.rs    # 27k chars: build APIs + payload embedding
└── bin/      # Embedded prebuilt trampoline binaries

Key abstractions

Type	Role
Trampoline enum / kind	The trampoline flavor: GUI script vs. console script vs. Python-loader.
prepend_to_trampoline	Append the script payload (the actual script bytes plus a target descriptor) to a stamped trampoline binary.
windows_script_launchers	Helpers for writing the .exe shim into a venv's Scripts/ directory.

How it works

Each trampoline is a small Win32 PE binary that:

1. Locates the venv's python.exe (relative path computed at install).
2. Reads its own appended payload (a frozen Python script + entry-point descriptor).
3. Spawns Python with that script and the real arguments.
4. Forwards exit status.

The build pipeline:

1. The actual trampoline source lives in crates/uv-trampoline/ (a separate, nightly-only, no_std crate excluded from the main workspace).
2. scripts/build-trampolines.sh builds those binaries on a Windows host (or via Wine / podman) and copies them into crates/uv-trampoline-builder/src/bin/.
3. crates/uv-trampoline-builder include_bytes!s those binaries and exposes them to the rest of uv.
4. At install time, uv-virtualenv and uv-install-wheel call into this crate to produce .exe shims with the right script appended.

The CI workflow .github/workflows/test-windows-trampolines.yml runs the trampoline tests across multiple Windows configurations, including QEMU and Wine for non-native runners.

Integration points

• uv-virtualenv uses these for the venv's python.exe shim.
• uv-install-wheel uses these for installed console scripts.
• uv-tool reuses them for tool-environment shims.

Entry points for modification

• Adding a launcher kind — extend the Trampoline enum and add a corresponding payload format. Update crates/uv-trampoline/ if a new binary is needed and rebuild via scripts/build-trampolines.sh.
• Resigning / re-stamping — lib.rs has the helpers for rewriting an existing trampoline's appended payload (used when a venv is moved).

Key source files

File	Purpose
crates/uv-trampoline-builder/src/lib.rs	The 27k-character build API.
crates/uv-trampoline-builder/src/bin/	The prebuilt PE binaries.
crates/uv-trampoline/	The actual trampoline source (separate workspace, nightly only).

See also

• uv-trampoline — the source that produces the embedded binaries.
• uv-virtualenv — the Windows venv consumer.
• uv-install-wheel — the console-script consumer.