Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 38 ยท Virtual Environments

Why Virtual Environments?

Learn the problem virtual environments solve, how sys.prefix and site-packages change inside one, and why every project deserves its own isolated environment.

Imagine two projects on one laptop. An old internal tool needs pandas 1.5; a new analysis needs pandas 2.2. A single Python installation has a single site-packages, so only one of them can be installed at a time. Install the new one and the old tool breaks. This clash is called dependency hell, and virtual environments are the standard solution.

A virtual environment is a directory containing its own site-packages and a small launcher for Python. When you run Python from that environment, imports look in that private directory first, so each project gets exactly the versions it needs, without touching the others or the system.

What problems it solves

  1. Conflicting versions between projects.
  2. A polluted system Python. Operating systems depend on their own Python and on specific versions of libraries; changing them can break system tools.
  3. Reproducibility. An environment contains only what the project installed, so you can list it, recreate it and share it.
  4. No admin rights. Installing into an environment never needs sudo.
  5. Easy disposal. Delete the folder and everything is gone. No uninstall ritual.
flowchart TD
    S["System Python<br/>(leave it alone)"]
    S --> A[".venv in project A<br/>pandas 1.5, numpy 1.24"]
    S --> B[".venv in project B<br/>pandas 2.2, numpy 2.1"]
    S --> C[".venv in project C<br/>django 5.1"]

Environments share the interpreter, but not the installed libraries.

What is inside

A typical environment created by python -m venv .venv looks like this on Linux and macOS (Windows uses Scripts instead of bin, and Lib\site-packages):

TEXT
.venv/
  pyvenv.cfg                 <- tells Python this is a venv
  bin/
    python  -> /usr/bin/python3.12   (a link or small copy)
    pip, activate, ...
  lib/python3.12/site-packages/   <- your packages go here

The key file is pyvenv.cfg. When the interpreter starts and finds that file next to (or one level above) its executable, it knows it is inside a virtual environment and sets two variables:

  • sys.base_prefix: where the real, underlying Python lives.
  • sys.prefix: the environment's own directory.

Outside any environment, the two are equal. Inside one, they differ. The standard recommended check is exactly that comparison.

Python Detecting a virtual environment with prefix and base_prefix

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

(In this browser Python, prefix and base prefix are the same because it is a single system-like installation; the second half shows what you would see in a real environment.)

How imports find the environment's packages

Python builds sys.path at startup. The site module adds the interpreter's site-packages directory, and in a virtual environment that is the environment's own. Nothing about your code changes. The same import numpy simply resolves to a different folder.

Python Where would packages be installed?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

purelib and platlib are the two places a wheel can unpack, depending on whether it contains compiled code. scripts is where command-line entry points (such as pip or pytest) are created, which is why activating an environment puts its bin directory first on PATH.

Activation is optional

source .venv/bin/activate (or .venv\Scripts\activate on Windows) edits PATH and your prompt so that typing python or pip picks the environment's version. It is a convenience only. You can always call the interpreter by path:

Terminal
.venv/bin/python -m pip install requests
.venv/bin/python app.py

This explicit style is the most reliable in scripts, cron jobs, editors and CI: no state to forget. Tools such as uv run and poetry run take the same approach, finding the project's environment and running inside it without you activating anything.

If you ever wonder which Python or pip you are really using, run python -c "import sys; print(sys.executable)" and python -m pip --version. Both print real paths.

Rules of thumb

  • One environment per project, usually in a .venv folder at the project root (editors and tools find it automatically).
  • Never commit it. Add .venv/ to .gitignore. An environment is built from the dependency list, not copied around, and it contains absolute paths that break when moved.
  • Never install into the global Python (use pip install --require-virtualenv or the environment variable PIP_REQUIRE_VIRTUALENV=true as a safety net).
  • Recreate rather than repair. If an environment misbehaves, delete it and rebuild from the requirements. This takes seconds with modern tools.
  • Use --system-site-packages only if you really need the system's packages; it weakens isolation.

What isolation does not cover

An environment isolates Python packages. It does not isolate system libraries (OpenSSL, libpq), the Python interpreter version itself (it is linked to one), other languages (Node, Java) or services (databases). When you need those too, reach for containers, covered in the Distribution and Docker chapter.

Python Simulating two environments with separate package sets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Inside a virtual environment, how do sys.prefix and sys.base_prefix compare?

    That difference is how Python (and your code) detects an active virtual environment.
  2. 2. Is activating an environment required to use it?

    Activation only adjusts PATH and the prompt. Calling the environment's interpreter by path is equivalent and more explicit.
  3. 3. What should you do with the .venv folder in version control?

    Environments are machine-specific. Share the dependency files, not the folder.
  4. 4. Which problem does a virtual environment NOT solve?

    Environments isolate Python packages only. Containers or system package managers handle system libraries and services.

Summary

  • A virtual environment is a private site-packages plus an interpreter launcher, marked by pyvenv.cfg.
  • Inside one, sys.prefix differs from sys.base_prefix.
  • Wheels unpack into purelib or platlib; scripts go to the environment's bin or Scripts.
  • Activation is a convenience; calling .venv/bin/python directly works the same.
  • One environment per project, never committed, easy to delete and recreate.
  • Environments isolate Python packages, not system libraries or services.

Next: Creating Environments with venv