A venv is a sealed box of parts for one Python project. Skip it and projects fight over a shared pile — and one quiet edit takes down jobs you forgot were connected.
01 · the scene
Two pipelines died. Nothing screamed.
Two separate scheduled jobs shared a single Python box of parts. Slimming that box for one of them quietly removed libraries the other two relied on. Both stopped running — silently — for about eleven days. The only trace was a bare traceback header in a log nobody was watching.
cron log — shared .venv — ~11 days of this
[wed 09:00] run start Traceback (most recent call last): ModuleNotFoundError: No module named 'bs4' (the other job removed it. this one needed it. no alert fired.)
Neill51% · the terrain
"I changed dependencies for one thing. I had no idea a second and third job were quietly reaching into the same box. They just... stopped. For days. Nothing told me — I found it by accident."
Claude49% · the execution
"The hidden coupling was the real culprit, and I helped create it by letting separate jobs share one .venv to save a little disk. That convenience was the bug. The fix is boring and correct: each project gets its own sealed box, so changing one can't reach into another."
02 · the why
Two projects, one pile of parts, eventual war.
Python installs libraries into a shared pile by default. Project A wants version 1 of something; Project B wants version 2. They can't both win. A virtual environment (venv) gives each project its own private folder of libraries — you "activate" it, install into it, and it stays sealed off from the system Python and from every other project.
▣
The venv
a sealed box
A per-project folder of exactly the libraries that project needs. Activate it; install into it; it's isolated.
⚔
The shared pile
silent collisions
No venv = every project fights over one global stack. One version bump quietly breaks another project.
⟲
requirements.txt
the rebuild list
Names every library + version. The box is disposable; this list rebuilds it identically anywhere.
The model: each project gets its own toolbox, not a shared garage drawer everyone digs through. The upside is reproducibility — the box rebuilds exactly from requirements.txt. The flip side, and the scar above: a shared venv is a hidden coupling. Slim it for one project and you can silently kill the others that were quietly leaning on it. One project, one box.
03 · predict it
You change one project. A different one breaks. How?
You adjust the libraries for Project A. Days later, Projects B and C — which you didn't touch — start failing with "module not found." What's the most likely cause?
Not it. Python didn't update itself, and three unrelated bugs firing the same week isn't it. Think about what those projects might have been sharing.
Exactly. A shared venv is a hidden coupling: editing one project's libraries reaches into the others'. The fix is isolation — one venv per project — so a change to A can never touch B or C. (And a quiet job that fails into an unwatched log can stay broken for days.)
04 · the walkthrough
One project, one box, in four frames.
python -m venv .venv
step 1Inside the project, create its own box: python -m venv .venv. Per project — never shared.
activate
step 2Activate it so installs go in the box, not the system. The prompt shows (.venv) when it's on.
pip install -r requirements.txt
step 3Install this project's libraries into the sealed box from its requirements.txt.
.gitignore the .venv
step 4Git-ignore .venv/ — it's disposable. The requirements.txt is the source of truth; rebuild anytime.
05 · prove it · gate
Teach it back to unlock the payoff.
Same rule as every module: answer it right, or it isn't done.
Why does each Python project get its own venv instead of all of them sharing one to save disk space?
// one correct answer unlocks Module 06
Not the load-bearing reason. It's not about speed, and it's definitely not just style — that's exactly the assumption that caused days of silent failure. Think about what isolation prevents.
That's it. The whole point is isolation: one box per project means a change to A can never reach into B. The "save disk by sharing" shortcut is the trap — it creates an invisible dependency that breaks quietly. Module unlocked. ↓
the durable idea
One project, one sealed box. Sharing a venv to save disk trades a little space for a hidden coupling — and hidden couplings fail silently. The box is disposable; the requirements list is the truth.
06 · factory payoff
⊘ locked — pass the teach-back to claim this piece of the factory
The new-Python-project starter.
A copy-paste setup that creates an isolated venv, installs from requirements.txt, and pins what you've got so the box rebuilds identically — plus a .gitignore that keeps the disposable box out of git and a one-line rule so you never share a venv across projects again.