Python Virtual Environments (venv): What They Are, Why You Need Them, and How to Use Them

Environment

What a virtual environment is

A virtual environment is just a folder. Inside it are:

• a link to a Python interpreter
• its own pip
• its own site-packages folder, where installed packages go
• a few small scripts that switch your terminal over to use all of the above

weather_tracker/
+-- .venv/                          < the virtual environment
|   +-- bin/
|   |   +-- activate                < script that turns the venv on
|   |   +-- python -> /usr/bin/python3.12
|   |   +-- pip
|   +-- lib/
|   |   +-- python3.12/
|   |       +-- site-packages/      < this project's installed packages
|   +-- pyvenv.cfg                  < records which Python it was made from
+-- main.py
+-- requirements.txt

When the venv is active, running python or pip uses the copies in .venv/bin/, and any package you install lands in this project's site-packages, not the system's.

Why you need one

1. Projects need different versions of the same package

Imagine two projects on the same machine:

Without virtual environments (one shared site-packages)

weather_tracker --needs--> requests 2.32 -+
                                          +--> system site-packages: only ONE version can exist x
old_script      --needs--> requests 2.25 -+

Installing one version replaces the other, and one of the projects breaks.

With virtual environments (one site-packages per project)

weather_tracker/.venv --> requests 2.32 y
old_script/.venv      --> requests 2.25 y

2. It protects your system's Python

Linux uses Python for its own tools (package managers, system utilities). If you install or upgrade packages system-wide, you can break software your OS depends on. Modern Ubuntu, Debian and others now refuse system-wide pip installs entirely:

$ pip install requests
error: externally-managed-environment

× This environment is externally managed

This isn't a bug. It's the system telling you to use a virtual environment.

3. It makes your project reproducible

Because the venv only contains what this project needs, you can write that list down in a requirements.txt file. Anyone (including you on another machine) can recreate the exact same setup with one command.

4. It's disposable

If a venv gets into a weird state, you delete the .venv folder and recreate it in seconds. Nothing outside your project is affected.

How activation works

"Activating" a venv doesn't install or copy anything. It runs a small script that puts .venv/bin at the front of your shell's PATH, the list of folders the shell searches when you type a command.

Before activating
$ which python3
/usr/bin/python3                                   ← system Python

After activating
$ which python
/home/you/projects/weather_tracker/.venv/bin/python ← the venv's Python

The script also:

• sets the VIRTUAL_ENV variable to the venv's path
• adds (.venv) to the start of your prompt, so you can see it's on
• creates the deactivate command, which undoes all of the above

Prerequisites

• Python 3 installed (python3 --version)
• A terminal (bash or zsh on Linux/macOS/WSL, or PowerShell on Windows)
• A project folder to work in

Step 1: Install the venv module

The venv module is part of Python itself, but Debian and Ubuntu ship it as a separate package. Install it once:

sudo apt update
sudo apt install python3-venv

Why: Debian-based distributions split Python into smaller packages. Without python3-venv, creating an environment fails with an ensurepip is not available error.

Step 2: Create the virtual environment

Go to your project folder and create the venv:

mkdir -p ~/projects/weather_tracker
cd ~/projects/weather_tracker
python3 -m venv .venv

Check what was created:

ls -a

Expected:

.  ..  .venv

Why each part:

• python3 -m venv runs the venv module that comes with Python. -m means "run this module as a program."
• .venv is the name of the folder to create. You can call it anything, but .venv is the common convention:
  • The leading dot hides it from normal ls output, so it doesn't clutter your project.
  • Editors like VS Code and tools like uv look for .venv automatically.
• You only do this once per project. The folder stays until you delete it.

Step 3: Activate it

source .venv/bin/activate

Your prompt now starts with (.venv):

(.venv) you@machine:~/projects/weather_tracker$

Verify that python points into the venv:

which python
python --version

Expected:

/home/you/projects/weather_tracker/.venv/bin/python
Python 3.12.3

Why source: a normal script runs in a separate process, so any changes it makes to PATH disappear when it finishes. source runs the script inside your current shell, so its changes stick.

Step 4: Install packages

With the venv active:

python -m pip install --upgrade pip
pip install requests rich
pip list

Expected (versions will differ):

Package            Version
------------------ ---------
certifi            2026.x.x
charset-normalizer 3.x.x
idna               3.x
markdown-it-py     3.x.x
pip                26.x
requests           2.32.x
rich               14.x.x
...

Why:

• Upgrading pip first avoids install errors caused by an outdated pip bundled with the system.
• pip list shows more than the two packages you asked for. Those extras are dependencies: packages that requests and rich need to work. pip installs them automatically.
• Everything lands in .venv/lib/python3.12/site-packages/. Your system Python never sees any of it.

Step 5: Record your dependencies

Create a requirements.txt file so the setup can be recreated later. There are two common approaches:

Option A: write it by hand, listing only the packages you chose:

requests
rich

Option B: generate it with pip freeze, which records everything installed, with exact versions:

pip freeze > requirements.txt
cat requirements.txt

certifi==2026.x.x
charset-normalizer==3.x.x
idna==3.x
requests==2.32.x
rich==14.x.x
...

To recreate the environment from the file, on any machine:

pip install -r requirements.txt

Why: the .venv folder itself never gets shared (see the next step). requirements.txt is the small, portable recipe for rebuilding it.

Step 6: Keep the venv out of Git

Create a .gitignore file in the project root containing:

.venv/
__pycache__/

Why:

• .venv holds thousands of files that are specific to your machine (including absolute paths). Committing it bloats the repository and won't work on anyone else's computer anyway.
• __pycache__/ holds compiled files Python generates automatically when it runs your code.
• Commit requirements.txt instead. It's the recipe, not the meal.

Step 7: Leave the virtual environment

When you're done working:

deactivate

The (.venv) disappears from your prompt, and python and pip go back to the system versions.

Why: deactivate restores the PATH and prompt exactly as they were before you activated. Closing the terminal window has the same effect, since activation only ever lived in that one shell session.

Resuming work later

Each time you come back to the project, in a new terminal:

cd ~/projects/weather_tracker
source .venv/bin/activate

That's all. Your packages are still installed from last time.

If the project uses Git, a good full routine is:

cd ~/projects/weather_tracker
git pull                              # get any changes
source .venv/bin/activate             # turn on the venv
pip install -r requirements.txt       # install anything new in requirements.txt

Why reinstall from requirements.txt: if you (or someone else) added a package on another machine, git pull brings in the updated requirements.txt, but not the package itself. Running the install again adds only what's missing; packages already installed are skipped.

Using a venv without activating it

Activation is a convenience for interactive work. Scripts, scheduled jobs (cron, systemd timers) and launcher scripts can skip it and call the venv's Python directly by its path:

~/projects/weather_tracker/.venv/bin/python ~/projects/weather_tracker/main.py

Why this works: the Python inside .venv/bin/ already knows which site-packages belongs to it. Activation only changes which python your shell finds first. Calling the full path gets the same result without changing anything.

The same applies to pip:

~/projects/weather_tracker/.venv/bin/pip install -r requirements.txt

Moving, renaming or rebuilding a venv

The fix is always the same: delete it and rebuild it from requirements.txt.

deactivate 2>/dev/null          # turn it off if it's on (ignore errors if not)
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Why this is fine: the venv was never the valuable part. Your code and requirements.txt are. Rebuilding takes seconds.

This same routine applies when:

• you clone a project onto a new machine
• you upgrade your system's Python to a new major version
• the venv seems corrupted or behaves strangely

Editor integration (VS Code)

VS Code can use your venv automatically:

1. Open the project folder (code . from the project root).
2. Press Ctrl+Shift+P and run Python: Select Interpreter.
3. Choose the entry that shows .venv.

Why: this tells VS Code's Python tools which packages exist, so it stops underlining your imports as missing. New terminals opened inside VS Code will also activate the venv for you. VS Code remembers the choice per project.

If .venv isn't listed, choose Enter interpreter path and type .venv/bin/python.

Windows (PowerShell)

The ideas are identical. Only the commands and folder names differ.

cd C:\projects\weather_tracker
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
deactivate

Differences from Linux:

• py is the Windows Python launcher. python works too if it's on your PATH.
• The scripts folder is Scripts\, not bin/.
• There's no source. You run the activation script directly.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Useful commands

All of these assume the venv is active.

A typical daily workflow

# Start of a session
cd ~/projects/weather_tracker
source .venv/bin/activate

# Work
python main.py
pip install some-new-package       # need something new?
pip freeze > requirements.txt      # or add it to requirements.txt by hand
git add requirements.txt
git commit -m "Add some-new-package"

# End of a session
deactivate

Alternatives worth knowing

venv is built into Python and is all most projects need. Two related tools are worth knowing about once you're comfortable:

Troubleshooting

Work through these in order. The first one that matches is usually the cause.

which python
pip show <package>

Quick reference

# --- One-time setup (per project) ---
sudo apt install python3-venv        # Debian/Ubuntu only, once per machine
cd ~/projects/weather_tracker
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests rich
pip freeze > requirements.txt
printf ".venv/\n__pycache__/\n" >> .gitignore

# --- Every session ---
cd ~/projects/weather_tracker
source .venv/bin/activate
# ...work...
deactivate

# --- Rebuild (moved folder, new machine, broken venv) ---
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# --- Run without activating ---
.venv/bin/python main.py

Key concepts

• Virtual environment (venv): a folder holding a project's own pip and installed packages, isolated from the system and from other projects.
• site-packages: the folder where installed packages live. Each venv has its own.
• Activation: running source .venv/bin/activate, which puts the venv's bin/ folder first in PATH for the current terminal only.
• PATH: the ordered list of folders your shell searches when you type a command. Whichever folder comes first wins.
• requirements.txt: the portable list of packages needed to rebuild the environment. Commit this, never the .venv folder.
• Externally managed environment: the protection on modern Linux that blocks system-wide pip installs, so OS tools that depend on Python can't be broken.
• Not a VM: a venv isolates Python packages only. It shares the operating system, the files and the Python interpreter with everything else.