Intuition The one core ideaA virtual environment is just a separate folder of packages plus one list of directories that Python looks through when you type import something. Every symbol on this page — sys.path, $PATH, site-packages, pip, conda — exists to answer a single question: "When I ask for a package, which copy on my disk does the computer actually load?"
This page builds up every word and symbol the parent 1.4.10 note uses, starting from things a curious 12-year-old already knows: files, folders, and typing commands. Nothing below assumes you have seen a terminal before.
Before any Python, we need the most basic object: a path .
A path is the written address of a file or folder on your computer, with each step separated by a separator .
On Linux/Mac the separator is a forward slash /: /usr/lib/python3.10/ means start at the top (/), go into usr, then lib, then python3.10.
On Windows the separator is a backslash \ and paths start from a drive letter: C:\Users\me\python3.10\.
Either way, a folder can contain other folders — this makes a tree . This page uses / throughout, but everything applies identically with \ on Windows.
What to look for in the figure: every rounded box is a folder, and the thin lines are the parent→child links. The deepest boxes (bottom row) hold actual package files. Notice the green branch (system packages) and the orange branch (venv packages) never touch — that separation is isolation. When the parent note says a venv is a "self-contained directory tree" , it means exactly one of these branches, kept apart from the others.
Why do we need this word first? Because isolation — the whole point of the topic — is nothing more than "keep packages in separate branches of this tree so they never touch."
When you write:
import numpy you are handing Python a name (numpy) and saying "go find the folder called this and load it." But Python does not search the whole disk — that would be slow. It only looks in a short, ordered list of folders.
A package is a folder of reusable Python code someone else wrote (e.g. numpy, pandas). You import it to use its tools instead of writing them yourself. See Python basics for how import fits the language.
Here is the single most important symbol in the whole topic.
sys.path
sys.path is a list of folder paths that Python searches, top to bottom , whenever you import something. It stops at the first folder that contains the package.
sys = a built-in module giving access to the Python interpreter's own settings..path = one setting inside it: the search list.
import sys print (sys.path) # ['', '/usr/lib/python3.10', '/usr/lib/python3.10/site-packages', ...]
Definition The empty string'' at the front
The first entry is an empty string ''. It is not a mistake — it is Python's way of writing "the current working directory" , i.e. the folder you were sitting in when you launched python. Because it comes first, Python checks your own project folder before anything else . That is why a file named random.py next to your script can accidentally shadow the real random package.
What to look for in the figure: read it like a checklist Python runs top to bottom. The first row is the '' current-folder entry. The blue arrow on the left shows the search direction . Python finds numpy in the highlighted green row, loads it, and the red "stop!" arrow shows it never looks at the rows below . This "first match wins" rule is the mechanism behind everything:
Intuition Why order is everythingIf we can put a new folder at the top of sys.path, Python will find our version of a package before the system's. A virtual environment does exactly this — it slips its own folder in near the front.
Common mistake "Python searches everywhere for the newest version"No. Python does not compare versions or search the whole disk. It walks sys.path in order and takes the first folder that has the name — even if a newer copy sits lower down. This is why forgetting to activate (section 7) silently loads the wrong version.
site-packages/
site-packages/ is the specific folder where pip and conda drop the files of any package you install. It always appears somewhere inside sys.path (otherwise imports would fail).
So the two symbols connect:
site-packages/ = where packages physically sit.sys.path = the list that includes that folder so Python knows to look there.
A virtual environment gives you a brand-new empty site-packages/ and puts it near the top of sys.path. That is the entire trick — a fresh drawer, checked first.
When a package is installed, alongside its code goes a small folder ending in .dist-info/.
.dist-info/
Metadata is data about the package: its name, its exact version number, and the list of other packages it needs. It lives in a .dist-info/ folder next to the code.
This is what pip freeze reads to print numpy==1.24.0.
The == you keep seeing is not maths equality — it is a filter :
Definition Version specifiers==, >=, <
These say which versions are acceptable :
numpy==1.24.0 → exactly this version.numpy>=1.20 → this version or newer .numpy<1.20 → strictly older than 1.20.
When two packages demand ranges that never overlap (e.g. >=1.20 and <1.20), no single version satisfies both — that is a version conflict , the "dependency hell" the parent note opens with.
Before we edit any lists, we need the tool that creates the isolated folder.
venv
venv is a module that ships inside Python itself (Python 3.3+), so nothing extra needs installing. You run it as a command:
python -m venv myenv
python -m venv = "Python, run your built-in venv module."myenv = the name of the new folder to create.
This builds myenv/ containing a copy of the interpreter, an empty site-packages/, and the activate scripts. Throughout this page, whenever you see a folder called venvmyenv, ml_project_env), it is one of these environments made by this command.
There are two search lists in play, and mixing them up causes most confusion. sys.path is for Python imports . $PATH is for which program the word python even runs .
$PATH
The shell is the program that reads the commands you type (like python or pip).
$PATH is a list of folders the shell searches — top to bottom, first match wins — to find the program you named. The $ marks it as a shell variable.
What to look for in the figure: the top block is $PATH before activation — python is found in a system folder. The bottom block is after activation — the orange venv/bin folder has been slipped in at the front, so now python resolves there first. It is the same "first match wins" rule as sys.path, just for programs instead of imports. When you activate an environment, the activate script runs:
export PATH = "/path/to/venv/bin: $PATH " export VIRTUAL_ENV = "/path/to/venv"
export = "make this variable visible to programs I run."Putting venv/bin in front means the word python now finds venv/bin/python first.
$VIRTUAL_ENV is a signpost variable recording which env is active (used to show the (venv) prompt).
Intuition One idea, two lists$PATH picks which python runs. That chosen python then has its own sys.path pointing at its own site-packages/ . Activation edits $PATH; that choice cascades down to imports. Two lists, one rule: prepend the new folder, first match wins.
Definition Activate / DeactivateActivate = run the activate script that edits $PATH for the current terminal only .
Deactivate = undo those edits, restoring the system's python.
Because the edits live in one terminal's memory, a new terminal starts fresh and must be activated again.
Common mistake "I activated it once, so it's active forever"Activation lives in a single shell session. Close the terminal → the edited $PATH is gone. Open a new one → you are back on system Python, silently loading the wrong versions. Always re-activate per terminal (or let your IDE auto-detect the venv ).
pip = "Pip Installs Packages." Downloads Python-only packages from PyPI (the Python Package Index, a big online store of packages) and drops them into site-packages/. It cannot install non-Python system libraries.
conda = a broader installer that manages the Python interpreter itself plus non-Python libraries (like CUDA or MKL) as pre-built binaries. Bigger downloads, but nothing needs compiling.
You now hold every symbol needed to read the parent note end to end.
The diagram below is written in Mermaid , a plain-text way to draw diagrams. Read it as a set of boxes joined by arrows : each box is a concept, and an arrow A --> B means "A must be understood before B." Follow the arrows top to bottom — everything funnels into the final "Virtual environment isolation" box.
Files and folders = a path
import asks for a package
sys.path = ordered search list
site-packages holds installed code
dist-info metadata and version equals
shell PATH picks which python runs
venv module creates the environment
activate prepends venv folder
Virtual environment isolation
pip and conda install into it
Related building blocks: reading/writing files like requirements.txt , packages such as NumPy you will install , and why MKL-optimized builds matter .
Test yourself — cover the right side and answer aloud.
What is a path ? The written address of a file or folder, steps separated by a separator (/ on Linux/Mac, \ on Windows).
What does import numpy make Python do? Search sys.path top-to-bottom for a folder named numpy and load the first match.
What is sys.path? The ordered list of folders Python searches on every import; first match wins.
What does the empty string '' mean at the front of sys.path? The current working directory — the folder you launched python from, checked before everything else.
What is site-packages/? The folder where pip/conda physically drop installed package files.
What command creates a virtual environment, and where does the tool come from? python -m venv myenv; venv is a module built into Python 3.3+, no install needed.
What does the rule "first match wins" imply if a folder is at the top of the list? Its packages are found before all others, so a venv's folder overrides system packages.
What does numpy==1.24.0 mean, and is it maths equality? "Install exactly version 1.24.0" — it is a version filter, not equality.
When do two version specifiers create a conflict ? When their allowed ranges never overlap (e.g. >=1.20 and <1.20), so no single version satisfies both.
What is $PATH and how does it differ from sys.path? $PATH is the shell's list for finding programs like python; sys.path is Python's list for finding imports . Both use first-match-wins.
What does the activate script actually change? It prepends venv/bin to $PATH and sets $VIRTUAL_ENV, for the current terminal only.
Why must you re-activate in every new terminal? Activation edits variables in one shell session's memory; a new terminal starts with system defaults.
One-line difference between pip and conda? pip installs Python-only packages from PyPI; conda also installs the Python interpreter and non-Python binaries.
