Python environments with uv and a target-scoped wheelhouse

A working .venv can hide a broken reconstruction path

A project has pyproject.toml, uv.lock, and a virtual environment that imports its dependency successfully. Then the only local wheel required by the target is removed. The warm environment still imports the package, yet a clean offline reconstruction cannot reinstall it. The green import proves the warm state works; it does not prove the environment can be recreated.

Your deliverable is Python Environment Closure Record v1. It binds project intent, lock freshness, Python and uv identity, target identity, local artifact inventory, clean-environment state, offline result, failure layer, and the remaining system boundary.

Three routes, one evidence bar

Foundation learners map each boundary before running commands. Repair learners isolate one stale-lock, interpreter, or artifact mismatch. Experienced learners may skip walkthroughs, but must retain hashes, tool/target identity, clean reconstruction evidence, a mutation, and residual-risk judgment.

Mental model: project → lock → interpreter/target → artifacts → clean environment

Keep five layers separate. pyproject.toml states dependency intent. uv.lock records a resolved project state but is not an OS or interpreter image. The selected Python interpreter and target platform determine compatibility constraints. A local artifact set must actually contain distributions compatible with that bounded target. Finally, reconstruction evidence must come from a clean environment; a warm .venv can preserve packages whose source artifacts are gone.

Native libraries, compilers, drivers, and other system resources remain outside this lesson unless they are explicitly represented as Python artifacts.

Build Python Environment Closure Record v1

Record pyproject_hash, uv_lock_hash, lock_fresh, python_identity, uv_identity, target_os_arch_abi, artifact_inventory_hash, clean_environment, offline_result, failure_layer, and residual_system_boundary. Label every material conclusion as OBSERVED, INFERRED, or UNKNOWN.

A defensible record answers two different questions: “Is the lock current for this project metadata?” and “Can this target reconstruct the locked environment from the evidence actually available locally?”

Current uv semantics used by this lesson

Current uv documentation distinguishes locking from synchronization. uv sync updates the project environment and performs an exact sync by default. The project is re-locked before sync unless --locked or --frozen is supplied. --locked checks that the lockfile is current and fails rather than changing it; --frozen uses the lockfile without checking whether project metadata has become stale. --offline disables network access and restricts uv to locally cached data and locally available files.

Those controls solve different problems. A frozen sync can intentionally ignore changed project metadata, so it is not evidence that the lock is fresh. An offline sync can still succeed from a warm cache, so the lab isolates cache state when proving local artifact sufficiency.

A wheelhouse is also bounded by compatibility. Wheels containing compiled code are commonly specific to OS, architecture, interpreter, and ABI. This lesson therefore records the target next to the artifact inventory instead of treating one wheel directory as universal.

Worked example: stale lock and missing artifact

Baseline: the fixture depends on demo-dep==1.0.0, uv.lock points to the packaged wheelhouse, and a clean environment with an isolated uv cache completes uv sync --locked --offline.

Stale metadata mutation: change the project requirement to demo-dep==2.0.0 without regenerating the lock. uv sync --locked --offline must not silently rewrite the lock; the correct evidence is a non-zero stale-lock result. --frozen would answer a different question because it trusts the existing lock without freshness validation.

Warm-state counterexample: restore the baseline, sync once, remove the wheel, and import from the existing .venv. The import can still succeed. Delete .venv, use a new empty uv cache, and retry the locked offline sync. Failure now locates the missing local-artifact boundary.

Four shortcuts that create false confidence

“uv.lock pins Python and the OS.” Repair: record interpreter and target identity separately.

“The import works, so recreation is proven.” Repair: destroy .venv and use a clean cache boundary.

“--frozen proves the lock is current.” Repair: use the documented locked/check semantics when freshness is the question.

“Our wheelhouse works everywhere.” Repair: bind the artifact inventory to an explicit target matrix and reject incompatible or missing wheels.

For experienced engineers: make the environment claim reviewable

In CI or release engineering, store target identity and artifact inventory beside the lock hash. When Python version, OS/architecture, dependency metadata, or native-extension requirements change, treat the previous closure result as target-scoped evidence that may need regeneration. A clean offline probe is especially valuable before declaring an air-gapped or disconnected deployment path ready.

Do not promote a successful install into a claim about application correctness. Installation closure and runtime correctness are separate evidence layers.

Exact reconstruction versus artifact cost

Maintaining one artifact set per supported target costs storage and build effort, but makes the claim auditable. A single broad wheelhouse is simpler until compiled wheels or Python-version boundaries appear. Universal pure-Python wheels can reduce duplication, yet that does not make every dependency universal.

Similarly, using caches speeds work but weakens the evidence value of a reconstruction test unless cache identity is controlled. For closure verification, a deliberately empty cache is often more informative than the fastest possible sync.

Lab: reconstruct from a clean local boundary

Use TOL004-LAB1. python setup_fixture.py creates a working copy inside the lab directory. python inspect_context.py records Python, uv, platform, paths, and artifact hashes. python run_uv_probe.py baseline performs a clean locked offline sync using an isolated cache and explicitly binds uv to the invoking Python with --python; retain the selected .venv interpreter identity returned by the probe. Then run the stale-lock and missing-artifact mutations independently, resetting between probes.

The packaged fixture requires no outbound network. If uv is unavailable, record UV_UNAVAILABLE; do not invent sync success or failure.

Minimum defensible evidence

Keep the exact project and lock hashes, executable identities, target tuple, the canonical artifact inventory hash (SHA-256 over sorted name<TAB>sha256<LF> lines), clean-environment declaration, offline command/result, mutation result, and residual system boundary. Distinguish LOCK_FRESHNESS, INTERPRETER_TARGET, LOCAL_ARTIFACT_AVAILABILITY, CLEAN_ENVIRONMENT, SYSTEM_RESIDUAL, and UNKNOWN_OR_MULTIPLE failure layers.

The strongest green result in this lesson is bounded: the locked project was reconstructable for the recorded target from the recorded local evidence under the recorded clean boundary. It does not prove another target, native system closure, or application correctness.

Assessment: diagnosis, decision, application, transfer

AS1 — Diagnosis: a warm .venv imports successfully after the wheel is removed. Identify the smallest evidence boundary that is still unproven.

AS2 — Decision: a team provides uv.lock and a wheel directory but no Python/target identity or clean reconstruction record. Decide ACCEPT, REJECT, or DEFER and state residual risk.

AS3 — Application: execute the local fixture, complete the closure matrix, and run stale-lock and missing-artifact mutations independently.

AS4 — Transfer: the target changes to a different Python/platform tuple and the supplied wheel set contains one incompatible or missing artifact. Decide whether the previous closure still holds and what must be regenerated.

Source and freshness boundary

Tool-specific claims are bounded to official uv and pip documentation rechecked on 2026-09-08. Current uv documentation still distinguishes lock freshness from frozen use, exact project sync, and offline local/cache behavior. Current pip documentation still describes wheelhouse installation bundles and warns that compiled wheels are commonly OS/architecture-specific.

The Bible review-due date is 2026-10-17. If command semantics or compatibility rules change, refresh the volatile source layer without expanding the lesson into OS/container closure.