How Python Virtual Environments Work
How Python virtual environments work, on a real Ubuntu laptop: why pip says Successfully installed and the next run says No module named, what is inside a .venv folder (a link to your Python, pyvenv.cfg and its own site-packages), how Python finds its packages without you activating anything, what activate really changes (just PATH), why two projects need two environments (numpy 1 vs numpy 2), and why a venv breaks when you rename its folder.
Installed, then not found
You install a Python package, pip says Successfully installed, and the next run says No module named numpy. Ana keeps her beekeeping club's hive log in Python. In window A she makes a virtual environment, installs numpy, and her script runs. In window B, same folder, same script, she gets that error: No module named numpy. So where did numpy go? And later, why does that environment stop working when all she does is rename the folder?
python3 -m venv .venv
source .venv/bin/activate
(.venv) ana@laptop:~/hive-log$ pip install numpy==1.26.4Collecting numpy==1.26.4 Downloading numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.metadata (62 kB) Downloading numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (13.9 MB) Installing collected packages: numpy Successfully installed numpy-1.26.4
(.venv) ana@laptop:~/hive-log$ python weigh.pyHive 3 gained 3.9 kg this week
python3 weigh.pyTraceback (most recent call last): File "/home/ana/hive-log/weigh.py", line 2, in <module> import numpy as np ModuleNotFoundError: No module named 'numpy'
Two Pythons
Here's the answer: numpy went into a folder that only one of the two windows looks in. A virtual environment is just a folder with three things: a link back to the Python you already have, a small settings file, and its own folder for packages. When Python starts from inside that folder, it reads the settings file, and it looks for imports in the folder's own packages, not the system's.

You can see it. The which command shows the program each window really runs. Window A runs the python inside the project's.venv folder. Window B runs the system's Python, in /usr/bin. The only difference: in window A, Ana ran activate. And pip show says where numpy went: into a folder called site-packages, where a Python keeps what it installs, inside.venv. In window A, the pip you type is the.venv's own pip, so it puts packages in the.venv's folder, and only the Python in that folder looks there. Inside an environment, python and python3 are the same link.
(.venv) ana@laptop:~/hive-log$ which python/home/ana/hive-log/.venv/bin/python
which python3/usr/bin/python3
(.venv) ana@laptop:~/hive-log$ pip show numpy | grep LocationLocation: /home/ana/hive-log/.venv/lib/python3.12/site-packages
Picture a shared workshop. There's one workbench everybody uses: that's Python itself. But each job gets its own toolbox, with a label saying which bench it goes with. Whatever you add to one job's toolbox, the next job never sees.

Inside the .venv folder
So what's actually in that folder? A bin folder, a lib folder, and one small file, pyvenv.cfg. The python in bin is not a copy of Python. It's a link that points back to /usr/bin/python3. The settings file says where that Python lives, its version, and one setting that leaves the system's own packages out. So a virtual environment can't change your Python version: it always runs the Python it was made from.
(.venv) ana@laptop:~/hive-log$ ls .venvbin include lib lib64 pyvenv.cfg
(.venv) ana@laptop:~/hive-log$ stat -c '%N' .venv/bin/python*'.venv/bin/python' -> 'python3' '.venv/bin/python3' -> '/usr/bin/python3' '.venv/bin/python3.12' -> 'python3'
(.venv) ana@laptop:~/hive-log$ cat .venv/pyvenv.cfghome = /usr/bin include-system-site-packages = false version = 3.12.3 executable = /usr/bin/python3.12 command = /usr/bin/python3 -m venv /home/ana/hive-log/.venv
The bin folder also holds the.venv's own pip, and the activate script, with a separate version for each kind of shell. Keep that pip in mind: it comes back when the folder moves.
(.venv) ana@laptop:~/hive-log$ ls .venv/binActivate.ps1 activate.csh f2py pip3 python python3.12 activate activate.fish pip pip3.12 python3
And lib holds the packages. site-packages has exactly what pip put there: numpy, and pip itself. The whole folder is 75 megabytes, nearly all of it numpy. Python's own standard library is just 29 megabytes, so an environment is mostly the packages you put in it.
(.venv) ana@laptop:~/hive-log$ ls .venv/lib/python3.12/site-packagesnumpy numpy-1.26.4.dist-info numpy.libs pip pip-24.0.dist-info
(.venv) ana@laptop:~/hive-log$ du -sh .venv /usr/lib/python3.1275M .venv 29M /usr/lib/python3.12
How Python finds its packages
But a link is the same program. So how does it know to use the.venv's packages? When Python starts, it looks for pyvenv.cfg next to its own program, or one folder up. The system's Python finds none, so its home base, called its prefix, is /usr. Start the.venv's python, in window B, which was never activated, and it finds the file: its prefix is the.venv folder.
python3 -c 'import sys; print(sys.prefix)'/usr
.venv/bin/python -c 'import sys; print(sys.prefix)'/home/ana/hive-log/.venv
So here's a question. In that same window, still not activated, Ana runs her script with the.venv's python, by its full path. Guess first: does it find numpy? It does. The hive log runs. Activating was never what made it work.
.venv/bin/python weigh.pyHive 3 gained 3.9 kg this week
What activate really does
Then what does activate do? Your shell keeps settings called environment variables. Ana saves them before and after activating, and compares. She leaves out the prompt, which gains the.venv label. Three lines differ. PATH is the list of folders your shell searches, left to right, when you type a command. Now it starts with the.venv's bin folder, and two new variables name the environment. That's all it does: typing python now finds the.venv's one first. deactivate puts PATH back.
env | grep -v ^PS1= | sort > /tmp/before; source .venv/bin/activate; env | grep -v ^PS1= | sort > /tmp/after
(.venv) ana@laptop:~/hive-log$ diff /tmp/before /tmp/after9c9 < PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin --- > PATH=/home/ana/hive-log/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin 16a17,18 > VIRTUAL_ENV=/home/ana/hive-log/.venv > VIRTUAL_ENV_PROMPT=(.venv)
(.venv) ana@laptop:~/hive-log$ which python/home/ana/hive-log/.venv/bin/python
(.venv) ana@laptop:~/hive-log$ deactivate; which python3/usr/bin/python3
Python's own documentation says the same. Inside a virtual environment, sys.prefix points to the environment, while Python still remembers the original it was made from. And you don't need to activate one at all: the full path to its python is enough.

It works the other way too: the environment can't see the system's packages either. Ubuntu installed a package called yaml for its own Python, and the system Python imports it. Inside the environment: No module named yaml. That's the line in pyvenv.cfg that asks whether to include the system's packages. It's set to false, so they stay out. You can let the system's packages in when you create one, but then your project quietly depends on what Ubuntu happened to install.
python3 -c 'import yaml; print(yaml.__file__)'/usr/lib/python3/dist-packages/yaml/__init__.py
(.venv) ana@laptop:~/hive-log$ python -c 'import yaml'Traceback (most recent call last): File "<string>", line 1, in <module> ModuleNotFoundError: No module named 'yaml'
Two projects, one environment
Now, why would you want one of these per project? Ana starts a second project, labels for the club's honey jars, still inside the hive log's environment. It needs numpy 2, and fails on 1.26. So she upgrades. pip takes 1.26.4 out, puts 2.5.5 in, and the labels print.
(.venv) ana@laptop:~/hive-log$ cd ~/honey-chart
(.venv) ana@laptop:~/honey-chart$ python labels.pyTraceback (most recent call last): File "/home/ana/honey-chart/labels.py", line 5, in <module> print("Jar labels:", ", ".join(np.strings.upper(jars))) ^^^^^^^^^^ File "/home/ana/hive-log/.venv/lib/python3.12/site-packages/numpy/__init__.py", line 333, in __getattr__ raise AttributeError("module {!r} has no attribute " AttributeError: module 'numpy' has no attribute 'strings'. Did you mean: 'string_'?
(.venv) ana@laptop:~/honey-chart$ pip install --upgrade numpyRequirement already satisfied: numpy in /home/ana/hive-log/.venv/lib/python3.12/site-packages (1.26.4) Collecting numpy Downloading numpy-2.5.5-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl.metadata (6.6 kB) Downloading numpy-2.5.5-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (15.3 MB) Installing collected packages: numpy Attempting uninstall: numpy Found existing installation: numpy 1.26.4 Uninstalling numpy-1.26.4: Successfully uninstalled numpy-1.26.4 Successfully installed numpy-2.5.5
(.venv) ana@laptop:~/honey-chart$ python labels.pyJar labels: CLOVER, HEATHER, LIME
Guess first: what happens to the hive log now? It breaks. numpy 2 removed a name the old script still uses. One environment can hold only one version of each package, so two projects that need different versions can't share it.
(.venv) ana@laptop:~/honey-chart$ python ~/hive-log/weigh.pyTraceback (most recent call last): File "/home/ana/hive-log/weigh.py", line 4, in <module> weights = np.array([31.2, 32.0, 33.4, 35.1], dtype=np.float_) ^^^^^^^^^ File "/home/ana/hive-log/.venv/lib/python3.12/site-packages/numpy/__init__.py", line 763, in __getattr__ raise AttributeError( AttributeError: `np.float_` was removed in the NumPy 2.0 release. Use `np.float64` instead.
The fix is one environment per project. In honey-chart, Ana makes its own.venv and installs numpy there. Back in the hive log, she puts numpy 1.26.4 back into that project's own.venv. pip list in each: two folders, two versions of numpy, on one Python. Both scripts run.
python3 -m venv .venv && source .venv/bin/activate
(.venv) ana@laptop:~/honey-chart$ pip install numpyCollecting numpy Using cached numpy-2.5.5-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl.metadata (6.6 kB) Using cached numpy-2.5.5-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (15.3 MB) Installing collected packages: numpy Successfully installed numpy-2.5.5
source .venv/bin/activate && pip install numpy==1.26.4Collecting numpy==1.26.4 Using cached numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.metadata (62 kB) Using cached numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (13.9 MB) Installing collected packages: numpy Attempting uninstall: numpy Found existing installation: numpy 2.5.5 Uninstalling numpy-2.5.5: Successfully uninstalled numpy-2.5.5 Successfully installed numpy-1.26.4
(.venv) ana@laptop:~/honey-chart$ pip listPackage Version ------- ------- numpy 2.5.5 pip 24.0
(.venv) ana@laptop:~/hive-log$ pip listPackage Version ------- ------- numpy 1.26.4 pip 24.0
(.venv) ana@laptop:~/hive-log$ python weigh.pyHive 3 gained 3.9 kg this week
Why a moved venv breaks
Remember the second question: why would renaming a folder break it? First, Ana writes down what the hive log needs: pip freeze lists what's installed, and she saves that list, numpy 1.26.4, into requirements.txt. Then she renames the project folder, from hive-log to hives. Moving it to another laptop would do the same. Now she runs its pip. It won't even start: cannot execute, required file not found.
(.venv) ana@laptop:~/hive-log$ pip freeze > requirements.txt; cat requirements.txtnumpy==1.26.4
(.venv) ana@laptop:~/hive-log$ deactivate; cd ~; mv hive-log hives; cd hives
.venv/bin/pip install pyyaml-bash: .venv/bin/pip: cannot execute: required file not found
The pip in bin is a small script, and its first line names the Python to run it with, by its full path. That path still says hive-log, a folder that no longer exists. The activate script has the old path written in too, and every script in bin starts the same way, so they all break at once.

That's why Python's documentation says a virtual environment isn't movable or copyable. It's like a toolbox labelled for one workbench: carry it somewhere else, and the label is wrong. You don't repair it. You make a new one.

So she deletes.venv, makes a fresh one, and installs everything listed in requirements.txt. With numpy already in pip's cache, that took about 2 seconds. The script runs again, and the new pip points at the new folder.
rm -rf .venv; python3 -m venv .venv; .venv/bin/pip install -r requirements.txtCollecting numpy==1.26.4 (from -r requirements.txt (line 1)) Using cached numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.metadata (62 kB) Using cached numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (13.9 MB) Installing collected packages: numpy Successfully installed numpy-1.26.4
.venv/bin/python weigh.pyHive 3 gained 3.9 kg this week
head -1 .venv/bin/pip#!/home/ana/hives/.venv/bin/python3
Habits that keep it working
One more trap. On Linux, scheduled jobs live in a file called the crontab, and a scheduled job never activates anything. So a line that says python3 runs the system's Python, with no numpy. This one runs every day at 7 PM. Name the.venv's python by its full path instead: it finds its own pyvenv.cfg, no activate needed.

So, four habits. One.venv per project, inside the project folder. Keep requirements.txt up to date and save it with your code, in Git if you use it. Never save the.venv folder itself: its paths only work on your machine. If you move or copy a project, delete the.venv and make a new one. And in scripts and scheduled jobs, call the.venv's python by its path.

Recap
So: a virtual environment is a folder, a link to a Python you already have, plus its own packages. pyvenv.cfg tells Python to use them. Activate only changes PATH. One workbench, a toolbox per project.

If No module named numpy makes sense now, subscribing brings more Python, worked out on a real machine.
Every command and every error in this video came from a real Ubuntu laptop, and the lab files are linked in the description. Thanks for watching Cloud Explainers.
Sources
- Python documentation, venv: Creation of virtual environments (How venvs work; not movable or copyable)
- PEP 405, Python Virtual Environments (pyvenv.cfg, home, include-system-site-packages)
- Python Packaging User Guide, Install packages in a virtual environment using pip and venv
- pip documentation, pip freeze and requirements files
- NumPy 2.0 migration guide (np.float_ removed)
Demos: one container on our own Mac standing in for a laptop; the beekeeping club and its scripts are made up. Every command, error and number was real. Watch the full video on YouTube.