An invoice-PDF renderer's .venv was copied from a laptop into the release bundle and the service dies at startup. Why does copying a venv break it, and what should ship instead?

### A virtual environment is a build output The single sentence that resolves this class of incident is: an environment directory is not source and not a portable bundle — it is a build artefact tied to the machine, the path and the interpreter that produced it. Treating it as something you can zip up and hand around produces failures that look nothing like their cause. ### The four absolute anchors inside an environment **1. `pyvenv.cfg`'s `home` key.** It records the base interpreter's directory as an absolute path. If the target host has no interpreter there, or has a different minor version there, the environment's standard library lookup is aimed at nothing. **2. The interpreter entry point.** `.venv/bin/python` is normally a symlink chain ending at the base binary. Copy the tree with a tool that follows symlinks and you get a real binary that may not match the target's shared libraries; copy it preserving symlinks and it dangles unless the base installation exists at the same path. **3. Console-script shebangs.** Every entry point installed into `.venv/bin` gets an absolute shebang naming the interpreter path at install time. Rename the project directory and the very same command that worked yesterday fails with `bad interpreter: ... no such file or directory`, while `.venv/bin/python -m ...` keeps working — an asymmetry that is confusing precisely because it is partial. **4. Installed compiled extensions.** A wheel with C extensions is built for one interpreter version, one platform and one C library. A laptop-built environment lands on a server with a different libc or CPU family and the import fails at load time, not at install time — so the error surfaces during startup, deep inside the application's import graph. ### Why the traceback misleads Startup failures caused by a broken environment surface as import errors, and import errors are read as application bugs. A renderer that fails while pulling in its font and layout dependencies looks exactly like a module-graph problem; teams reach for the familiar explanation — a circular import introduced by the last refactor — and spend an afternoon rearranging imports that were never wrong. The tell is that the same commit works on the machine that built the environment, and that the failure moves when the *directory* moves, not when the code changes. ### The thirty-second triage 1. `head -1 .venv/bin/<script>` — does that shebang path exist on this host? 2. `.venv/bin/python -c "import sys; print(sys.executable, sys.prefix, sys.base_prefix)"` — does the interpreter start at all, and does it point where you expect? 3. `cat .venv/pyvenv.cfg` — is `home` a path that exists here, and does `version` match the interpreter the host actually has? 4. Only if all three are clean should you start reading the application's import graph. ### What to ship instead Ship the *inputs*, not the environment. The release bundle carries the source and a pinned requirement set; the deployment step runs `python -m venv --clear /srv/app/.venv` on the target and installs into it. This gives you an environment built by the target's own interpreter, with wheels chosen for the target's platform, and it makes the interpreter version an explicit, checked part of the deployment rather than an accident of whose laptop cut the release. Two related moves are worth knowing. `python -m venv --upgrade .venv` re-points an existing environment at the interpreter running the command, which covers an in-place upgrade of the base installation — but it does not rewrite the shebangs of already-installed console scripts, so it is a repair, not a rebuild. And invoking tools as `.venv/bin/python -m <module>` instead of through their console script removes one of the four anchors entirely, which is a cheap habit that survives a directory rename. ### The judgement to demonstrate An environment is cheap to rebuild and expensive to move. Version-control the requirement pins and the command that builds the environment; never version-control or copy the environment itself. When a service fails at startup after a deployment that did not change any code, suspect the environment before the import graph. ### What to cache instead, in CI The instinct that produced the copied environment usually reappears as "let us cache the environment directory between builds". It has the same defect the moment the runner image or the interpreter changes underneath it. Cache the things that are genuinely position-independent instead — the downloaded distributions and the locally built wheels — and let each build create the environment fresh from pins. Creating an empty environment costs a fraction of a second, installing from a warm wheel cache costs little more, and in return the build's result does not depend on what a previous build happened to leave behind.