Virtual Environments

The problem they solve

Install packages into the system Python and every project shares them. Project A needs version 1 of a library, project B needs version 2, and only one can win. Worse, a system upgrade can break tools your operating system depends on.

A virtual environment is a folder holding its own interpreter and its own packages. One per project, and the conflict disappears.

Making one

cd my-project
python -m venv .venv

That creates a .venv folder. The name is a convention; editors look for it.

Activating

source .venv/bin/activate          # macOS and Linux
.venv\Scripts\activate             # Windows, cmd or PowerShell

Your prompt gains a (.venv) prefix. From then on python and pip mean the ones inside the environment:

python -m pip install requests
python -m pip list
deactivate

deactivate puts everything back.

Checking which Python you are on

import sys
print(sys.prefix != "" and sys.base_prefix != "")
print(sys.prefix == sys.base_prefix)

True
True

Inside an active environment those two differ, so the second line prints False. On this page there is no environment, so they are equal. It is the quickest way to answer "am I actually in my venv?".

Recording what you need

python -m pip freeze > requirements.txt

Someone else — or you on another machine — then rebuilds it exactly:

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

Do not commit it

Add this to .gitignore:

.venv/

The folder holds hundreds of megabytes of platform-specific binaries. The requirements.txt is the part worth keeping in version control: it is the recipe, not the meal.

Common problems

"I installed it but the import fails." You installed into a different interpreter. Use python -m pip install, not bare pip, and check sys.executable.

The editor cannot see the packages. Point it at the environment's interpreter. In VS Code that is the Python: Select Interpreter command.

Activation fails on Windows PowerShell. The execution policy blocks the script:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

You do not always have to activate

Running the environment's interpreter directly works and is handy in scripts:

.venv/bin/python -m pip install requests
.venv/bin/python main.py

Newer tools

uv and poetry do the same job with lockfiles and faster installs, and uv in particular has become popular:

uv venv
uv pip install requests

They are worth knowing about. venv is built in, works everywhere, and is enough to start.