Python Virtual Environments & pip

A virtual environment is an isolated Python installation for a single project. It keeps each project’s packages separate so versions never clash, and it keeps your global Python clean. pip is the tool that installs and manages those packages. (For installing Python itself, see the Installation page.)

Golden rule: one virtual environment per project, and never pip install into your system Python.

diagram what a virtual environment actually changes mermaid

  flowchart TD
  A["python -m venv .venv"] --> B[".venv/ with its own site-packages"]
  B --> C["pyvenv.cfg records the base interpreter"]
  D["activate"] --> E["puts .venv/bin (Scripts) first on PATH"]
  E --> F["'python' and 'pip' now resolve INSIDE the venv"]
  F --> G["pip install writes to .venv/site-packages"]
  H["sys.prefix"] --> I["the venv directory"]
  J["sys.base_prefix"] --> K["the original install -- unchanged"]
  I --> L["prefix != base_prefix  ->  you are in a venv"]
  K --> L

A venv is not a copy of Python. It is a directory with its own site-packages and a marker that tells the interpreter to look there, plus scripts that put its bin directory first on PATH. The interpreter itself is still the base one, which is why sys.base_prefix keeps pointing at the original install.

Both interpreters on this machine, measured

	sys.prefix	sys.base_prefix	In a venv?	import flask
system Python	…/pythoncore-3.14-64	the same	no	PackageNotFoundError
a venv	…/scratchpad/flaskenv	…/pythoncore-3.14-64	yes	works

That is the whole mechanism, and it gives you the reliable check:

python

import sys
in_venv = sys.prefix != sys.base_prefix

VIRTUAL_ENV in the environment is set by the activate script, so it is absent when you run the venv’s interpreter by full path without activating — which is exactly what a cron job or a systemd unit does. Prefer the sys.prefix comparison.

The practical consequence: activation is only PATH manipulation. Running /path/.venv/bin/python script.py uses the venv whether or not you activated it, and running plain python after activating a different shell does not.

Why isolate?

Without isolation, every project shares one set of packages:

• Project A needs django==3.2, Project B needs django==4.2 — they can’t coexist globally.
• A global install can break system tools that rely on specific versions.
• You can’t reproduce “exactly what this project needs” for a teammate or server.

A virtual environment solves all three.

Creating an environment with venv

venv ships with Python. Create an environment (commonly named .venv) in your project folder:

terminal

# Create a virtual environment in the .venv folder
python -m venv .venv

This makes a .venv/ directory containing a private copy of Python and a place for packages.

Activating and deactivating

You must activate the environment so python and pip point at it.

macOS / Linux

source .venv/bin/activate

Windows (PowerShell)

.venv\Scripts\Activate.ps1

Once active, your prompt usually shows (.venv). To leave it:

terminal

deactivate

Tip: add .venv/ to your .gitignore — environments are rebuilt from requirements.txt, not committed.

Installing packages with pip

With the environment active:

terminal

pip install requests              # latest version
pip install "django==4.2"         # a specific version
pip install "flask>=2,<3"         # a version range
pip install --upgrade requests    # upgrade to the newest
pip uninstall requests            # remove a package

Command	Does
pip install NAME	Install the latest version.
pip install NAME==X.Y	Install an exact version.
pip install --upgrade NAME	Upgrade a package.
pip uninstall NAME	Remove a package.
pip list	List installed packages.
pip show NAME	Show details about a package.

requirements.txt — reproducible installs

Record exact versions so anyone can recreate the environment.

terminal

# Save the current environment's packages
pip freeze > requirements.txt
 
# Recreate it elsewhere (in a fresh venv)
pip install -r requirements.txt

A requirements.txt looks like:

requirements.txt

requests==2.31.0
flask==3.0.0
python-dotenv==1.0.0

A typical project workflow

terminal

mkdir myproject && cd myproject
python -m venv .venv
source .venv/bin/activate          # (Windows: .venv\Scripts\Activate.ps1)
pip install requests flask
pip freeze > requirements.txt
# ... write code ...
deactivate

Common pitfalls

• Forgetting to activate — pip install then lands in global Python. Check your prompt for (.venv).
• Committing .venv/ — it’s large and machine-specific; commit requirements.txt instead.
• Mixing pip and the system package manager — inside a venv, always use pip.
• python vs python3 — on some systems the command is python3; the same goes for pip/pip3.

Practice Exercises

These run plain Python that mirrors what the tools do under the hood.

Exercise 1 – Check the running Python version

pch.exerciseTag pch.exerciseTitle

Exercise 2 – Parse a requirements line

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Build a pip install command

pch.exerciseTag pch.exerciseTitle

sketch A venv is a directory and two variables, not a copy of Python p5.js Pause Restart

The interpreter is still the base one -- that is why sys.base_prefix keeps pointing at the original install. What changes is sys.prefix, and therefore where imports are found. Activation only edits PATH, which is why running the venv's interpreter by full path works whether or not you activated anything.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. How do you reliably detect that code is running inside a virtual environment?

   A Check `VIRTUAL_ENV` in the environment B Compare `sys.prefix` with `sys.base_prefix` C Look for a `.venv` folder D Call `venv.is_active()`
   pch.quizShowAnswer

   B — Compare `sys.prefix` with `sys.base_prefix` — Verified on both interpreters here. `VIRTUAL_ENV` is set by the activate SCRIPT, so it is absent when a cron job or service runs the venv's interpreter by full path — which is the usual deployment shape.

2. What does `sys.base_prefix` point at inside a venv?

   A The venv directory B The original Python installation C The current working directory D It is unset
   pch.quizShowAnswer

   B — The original Python installation — A venv is not a copy of Python — the interpreter is still the base one. That is exactly what makes the two-variable comparison work as a test.

3. What does activating a virtual environment actually do?

   A Starts a sandbox process B Puts the venv's script directory first on `PATH` C Copies the interpreter D Rewrites `sys.path` permanently
   pch.quizShowAnswer

   B — Puts the venv's script directory first on `PATH` — It is PATH manipulation plus a prompt change. `/path/.venv/bin/python script.py` uses the venv with no activation at all.

4. Why does a cron job often fail with `ModuleNotFoundError` when the same command works in your shell?

   A Cron has a different Python version B Cron does not run your shell, so no venv is activated and PATH is minimal C Cron blocks imports D The virtualenv expires
   pch.quizShowAnswer

   B — Cron does not run your shell, so no venv is activated and PATH is minimal — Use the absolute interpreter path — `/path/.venv/bin/python` — rather than relying on activation. The same reasoning covers the working directory, which is HOME rather than your project.

Summary

• A virtual environment isolates one project’s packages; create it with python -m venv .venv.
• Activate it before working (source .venv/bin/activate or Activate.ps1), deactivate to leave.
• Use pip to install, upgrade, uninstall, and list packages.
• Pin versions with pip freeze > requirements.txt and restore with pip install -r requirements.txt.
• Commit requirements.txt, not the .venv/ folder.