Visual walkthrough — Virtual environments — venv, pip, requirements.txt

This is the deep-dive companion to the parent topic. The parent told you a venv is "PATH manipulation + a config file." Here we derive that claim from absolute zero and draw every step.

Step 1 — What "import" really means: a search through folders

WHAT. When you write import requests, Python does not look inside your computer for a magic file. It has a plain ordered list of folders, and it walks that list top-to-bottom asking each folder: "do you contain requests?" The first folder that says yes wins. That list is called ==sys.path== (see Python import system and sys.path).

WHY this matters. If we can control which folders are on that list, and in what order, we control which copy of a package gets imported. That single idea is the entire foundation of virtual environments. So before anything else, we must see the list.

PICTURE. Below, the yellow box is your running program. The stack of folders on the right is sys.path. Python checks them in order — the red arrow shows the search stopping at the first match.

Step 2 — The problem: one global site-packages for everyone

WHAT. Without a venv, there is exactly one site-packages folder shared by every project on the machine. Every pip install dumps into it. Every import reads from it.

WHY it breaks. A folder can only hold one version of Django at a time — a folder is not a magic multi-version container. So if Project A pinned Django==3.2 and you run pip install Django==4.2 for Project B, the second install overwrites the first. Project A now silently imports 4.2 and may crash. This is dependency hell.

PICTURE. Two projects, one shared shelf. The coral arrows show both reaching for the same box — and the box can only hold one label at a time.

Step 3 — The fix in one idea: give each project its own folder on sys.path

WHAT. A virtual environment creates a new, empty site-packages folder that belongs to this project only, and arranges for Python to search that folder instead of the global one.

WHY this is enough. From Step 1, imports resolve against whatever site-packages is on sys.path. If Project A's Python searches folder $S_A$ and Project B's Python searches a different folder $S_B$, then installing Django==4.2 into $S_B$ cannot possibly touch $S_A$. Isolation falls straight out of "different folder = different search path."

PICTURE. The same two projects, now with separate shelves. Each coral arrow reaches into its own private box — no collision is even possible.

Step 4 — What python -m venv .venv builds on disk

WHAT. The command python -m venv .venv creates a folder named .venv containing three things — and nothing that needs downloading (it copies/links the Python you already ran):

Reading the equation term by term:

• pyvenv.cfg — a tiny text file whose one job is a line like home = /usr/bin telling the env where the real Python lives so it can still find the standard library (you don't get a private copy of os, math, etc.).
• bin/ (Linux/macOS) or Scripts/ (Windows) — holds a python launcher and a private pip (pip and PyPI) that is pre-wired to install into this env's site-packages.
• site-packages/ — empty on creation. This is the private shelf from Step 3.

WHY it's built this way. We want isolation for third-party packages but we do not want to duplicate the whole standard library (wasteful). So the config file borrows the stdlib from base Python, while the fresh empty site-packages gives us a clean slate for installs.

PICTURE. The anatomy of the .venv folder, with each part labelled by the job it does.

Step 5 — What activate actually changes: the PATH variable

WHAT. Your shell finds the python command by searching another ordered list of folders — the operating-system ==PATH== variable (different from sys.path, same idea one level up). activate prepends the env's bin/ folder to the front of PATH.

• .venv/bin at the front — because the shell stops at the first match, putting the env first means typing python now runs the env's python, and pip runs the env's pip.
• the old entries — still present, just lower priority. Nothing was deleted; the search order was reshuffled.

WHY this is the whole trick. The env's python is configured so that when it boots, its site-packages is on sys.path. So: activate fixes PATH → typing python/pip hits the env copies → those copies read/write the env's site-packages. Two path lists (one for the shell, one for Python) chained together give you full isolation. No magic — just reordering search lists.

PICTURE. Before/after of PATH. The lavender segment .venv/bin slides to the front; the green arrow shows python now resolving there.

Step 6 — pip freeze > requirements.txt: recording the shelf

WHAT. After installing, pip freeze reads the env's site-packages, lists every package with its exact version, and > writes that list into requirements.txt.

• name==version — a pin: == means "exactly this version, no other." This is what makes rebuilds reproducible (see Semantic versioning).
• "every package" — including transitive dependencies (the packages your packages needed), which is why pip install flask can produce a dozen lines.

WHY. From Step 3, isolation is per-machine. To share the state of a shelf across machines, we don't ship the shelf (it's OS-specific and huge) — we ship the recipe to rebuild it. That's the .txt file. See .gitignore best practices for why .venv/ itself is ignored, and Reproducible builds and Docker for pushing this further.

PICTURE. The env's site-packages on the left; the arrow "freeze" flattening it into a plain text list on the right.

Step 7 — Edge & degenerate cases (every scenario shown)

WHAT. Let's walk the corners so you never hit an unshown case:

1. Empty env, no activation — PATH unchanged, python = system Python, installs pollute global site-packages. (This is the "forgot to activate" trap.)
2. Activated but empty site-packages — import requests raises ModuleNotFoundError, because the shelf is genuinely empty. Correct behaviour, not a bug.
3. requirements.txt empty — pip install -r requirements.txt does nothing; you get a working env with only the standard library.
4. Two envs, same package different versions — perfectly fine; different folders (Step 3) means no interaction at all.
5. deactivate — restores the old PATH (saved when you activated). Reverses Step 5 exactly; nothing is deleted from disk, the shelf still exists.

WHY show these. Each is a place where beginners think "something broke." Every one is just Steps 1–6 running as designed.

PICTURE. A decision map: is the env activated? is the package installed? — leading to what import does in each corner.

The one-picture summary

Everything above is one chain: import/python follow ordered lists → venv gives each project its own site-packages and reorders those lists so the env wins → freeze records the shelf as a text recipe.

Active recall