Python Virtual Environments: venv, Activation, and requirements.txt

The Problem Virtual Environments Solve

Install Python, run pip install requests, and the package lands in a single global place. That works fine for one project. By the third project, it starts to hurt:

• Project A needs django==3.2. Project B needs django==5.0. Only one of them can have their version installed globally.
• You want to try a new library but don't want it polluting every other project on your machine.
• A teammate clones your repo and has no idea which versions of which packages you actually depended on.

A virtual environment is the fix. It's a self-contained folder holding a Python interpreter and its own library install directory. When the environment is activated, python and pip in your terminal point inside that folder instead of your system-wide Python. Packages installed there stay there.

Creating One With venv

venv ships with Python 3 — nothing to install. From inside your project directory:

python3 -m venv .venv

That creates a .venv/ folder next to your code. The name .venv is a near-universal convention; the leading dot keeps it out of most directory listings, and editors like VS Code automatically detect it.

After the command finishes, the folder contains a full Python install (tens of megabytes, which is normal) and a pip of its own.

Activating the Environment

Activation rewrites your shell's PATH so python and pip resolve to the ones inside .venv/. The command depends on your platform:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Your prompt gets a (.venv) prefix while the environment is active — a visual reminder. Any pip install you run now affects only this project.

When you're done for the day, deactivate restores the previous state:

deactivate

You don't need to deactivate before closing the terminal — quitting the shell is the same thing.

Installing Packages

With the environment active, install what you need:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Check what's installed with pip list. Remove something with pip uninstall requests.

The installed packages live under .venv/lib/pythonX.Y/site-packages/. You never edit those by hand — pip manages the directory.

Pinning Dependencies With requirements.txt

Your project is reproducible only if others can install the same versions you used. The simplest way to capture that is requirements.txt:

pip freeze > requirements.txt

pip freeze prints every installed package with its exact version. Commit the file to git.

When a collaborator (or future you on a new machine) clones the repo:

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

Three commands and their environment matches yours.

A Common Project Setup

The full workflow, start to finish:

# Create the project folder
mkdir my_tool && cd my_tool

# Create and activate the venv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install requests rich

# Save them
pip freeze > requirements.txt

# Work on your code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# When you're done
deactivate

Add .venv to Your .gitignore

Never commit the .venv/ folder. It's platform-specific and reproducible from requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

Committing it would bloat the repo, break on other machines, and leak whatever OS-specific binaries your interpreter has.

Which Python Version?

By default, python3 -m venv .venv uses whichever python3 your shell resolves to. If you have multiple Pythons installed (say, 3.12 and 3.13), be explicit about which one:

python3.13 -m venv .venv

Once the venv exists, its interpreter is pinned — running python inside the activated venv always uses that specific version, even if your system Python changes.

When Things Go Wrong

A few common symptoms and fixes:

• pip install works, but my imports fail. You installed against the wrong Python. Activate the venv before pip install, and re-check with which python (macOS/Linux) or where python (Windows).
• "ModuleNotFoundError" after activation. The venv was created without certain libraries, or the package installed into a different venv. pip list shows what's actually in the current one.
• Activation script not found on Windows. PowerShell may block unsigned scripts. Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once to allow local scripts.
• "No module named venv". On some Linux distributions, venv is a separate package. sudo apt install python3-venv on Debian/Ubuntu.

Beyond venv: Poetry, uv, pipenv

Once you're comfortable with venv + pip + requirements.txt, you'll run into tools that wrap the same ideas with better ergonomics:

• Poetry — manages venvs, dependencies, and packaging with a single pyproject.toml.
• uv — a very fast drop-in pip replacement; handles venvs too.
• pipenv — an older tool that popularised the "Pipfile + Pipfile.lock" pattern.

All of them are good. None of them are required for learning. Get comfortable with the plain venv workflow first; the rest are optimizations.

What to Take Away

• Every real Python project gets its own virtual environment.
• Create one with python3 -m venv .venv, activate it, then pip install freely.
• Pin dependencies with pip freeze > requirements.txt and commit that file.
• Never commit the .venv/ folder itself.
• When imports misbehave, check which Python is active first.

Next: The __main__ Pattern

With a project set up and packages installed, one last idiom closes out this chapter — the if __name__ == "__main__" guard. It's in almost every Python file meant to be run as a script, and it's the subject of the next page.