Python Virtual Environments Explained (venv, pip, and requirements.txt)

Introduction

Sooner or later it happens: Project A needs requests 2.28, Project B needs 2.31, and pip happily breaks one while installing the other. Virtual environments are the fix — and the concept is simpler than the jargon suggests: each project gets its own private Python and its own private packages.

This guide explains what actually happens when you run those magic commands, so venvs stop being a ritual and start being a tool.

The Problem: One Global Python

By default, pip install puts packages into your system-wide Python. Every project shares that one pile of packages. Consequences:

Version conflicts between projects (the A/B problem above).
Uninstalling a project leaves its packages behind, forever accumulating.
“Works on my machine” — because your machine’s global pile is unique.

A virtual environment is just a folder containing its own Python and its own site-packages. Activating it makes your terminal use that folder’s Python. Nothing more mysterious than that.

Step 1: Create and Activate

cd my-project
python -m venv .venv

# Activate:
source .venv/bin/activate        # macOS / Linux
.venv\Scripts\activate           # Windows

Your prompt now shows (.venv). Proof it worked:

which python        # macOS/Linux — points inside .venv
where python        # Windows
pip install streamlit

The Streamlit you just installed went into .venv/lib/.../site-packages — invisible to every other project on your machine.

Step 2: requirements.txt — Your Project’s Recipe

pip freeze > requirements.txt

This writes every installed package with exact versions (streamlit==1.41.1). Anyone — future you, a teammate, a deployment server — recreates the identical environment with:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

This two-file pair (code + requirements.txt) is what makes a project portable. It’s also what deployment platforms ask for — the Streamlit deployment guide depends entirely on this file.

Step 3: The Habits That Matter

One venv per project — never share, never activate globally.
Name it .venv — the dot hides it, the name is tooling convention.
Never commit .venv — add it to .gitignore (see the Git guide); it’s thousands of files of machine-specific binaries. requirements.txt is the portable form.
Install with the venv active — pip outside a venv pollutes your system Python.
Freeze after adding packages — new import working locally but missing on deploy is 90% a forgotten pip freeze.

Step 4: Everyday Management

deactivate                          # leave the venv
pip list                            # what's installed here
pip show streamlit                  # version + location of one package
pip install --upgrade streamlit     # update one package
pip uninstall requests              # remove one

Removing a venv is just deleting the folder — it’s self-contained by design. Recreating it is two commands plus one install, which is why venvs are disposable: don’t clean them, replace them.

Common Errors & Fixes

“pip installed it but Python can’t import it” — your venv isn’t active, or your editor is using the system interpreter. Check which python and set your editor’s interpreter to .venv/bin/python.
activate script blocked on Windows — PowerShell’s execution policy; run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser once.
ModuleNotFoundError in a running script but fine in the terminal — two different Pythons; your IDE launched the script with the global interpreter.
requirements.txt has everything on my machine — you froze from the global Python; activate the project venv first, then freeze.

Key Concepts

Isolation — private interpreter + private site-packages per project.
Activation — a terminal-level PATH switch, not an installation.
pip freeze — the exact recipe for reproduction.
Disposable by design — delete and recreate beats debugging environments.

What to Try Next

Convert an existing project: create .venv, install its imports, freeze the requirements.
Try uv or poetry — faster, fancier front-ends over the same concept.
Deploy a venv-based project to the cloud — the Streamlit deployment walkthrough uses exactly this recipe.
Add .venv/ to a global gitignore so you never think about it again.

FAQ

Do I really need a venv for a tiny script?

Strictly no, practically yes — it costs ten seconds and builds the habit that saves you on the day packages conflict. Scripts that grow into projects never announce themselves in advance.

Where did the name ‘venv’ come from?

It’s the standard-library module (python -m venv) since Python 3.3. Before that, virtualenv was a third-party package doing the same job — the name stuck as the generic term.

Technically yes; practically never. The moment they need different versions of anything, you’re back to the original problem — with extra confusion about which venv you’re in.