Python Virtual Environments: venv, pip and requirements.txt

By Engr. Henry Akpan

Why Every Python Project Needs Its Own Environment

You build a final-year project with Flask 2 and pandas 1.5. A year later you start a new project that needs Flask 3. If both projects share one Python installation, upgrading Flask for the new one can break the old one. Worse, when your supervisor or a teammate tries to run your code, they don't know which packages and versions you used. Python virtual environments solve both problems: each project gets its own private folder of installed packages, and a requirements.txt file records exactly what is needed. This tutorial explains what a virtual environment is, how to create and activate one with venv on Windows, macOS and Linux, how to install packages with pip, freeze and restore requirements, and the habits that save hours of "it works on my computer" problems.

What Are Python Virtual Environments?

A virtual environment is a folder containing:

  • a link to (or copy of) a Python interpreter;
  • its own site-packages folder where pip installs packages;
  • activation scripts that make your terminal use this Python and pip instead of the system ones.

Packages installed inside one environment are invisible to other environments and to the main Python installation. You can have as many environments as you like, one per project, each with different package versions. Deleting the folder deletes the environment completely, without affecting anything else.

Creating a Virtual Environment with venv

Python 3 includes the venv module, so nothing extra needs installing. Open a terminal in your project folder and run:

In a terminal:

$ cd my-project
$ python -m venv .venv

This creates a folder called .venv (the name is a common convention; venv or env are also used). On some Linux and macOS systems the command is python3 instead of python. On Windows, if python is not found, try the launcher: py -m venv .venv.

Activating and Deactivating

Activation changes your terminal session so that python and pip refer to the environment. The command depends on your system:

  • Windows (Command Prompt): .venv\Scripts\activate.bat
  • Windows (PowerShell): .venv\Scripts\Activate.ps1
  • macOS and Linux (bash or zsh): source .venv/bin/activate

When it works, the prompt shows the environment's name in brackets, such as (.venv). To leave the environment, type deactivate.

PowerShell error? If PowerShell says running scripts is disabled, allow scripts for your user once with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, or use Command Prompt instead.

You don't strictly have to activate. You can call the environment's Python directly, for example .venv\Scripts\python app.py on Windows or .venv/bin/python app.py on Linux. Editors such as VS Code detect the .venv folder and offer to use it automatically.

Checking Which Python Is Running

A quick Python check tells you whether you are inside a virtual environment. In a virtual environment, sys.prefix points to the environment folder, while sys.base_prefix still points to the original installation:

import sys

in_venv = sys.prefix != sys.base_prefix
print("Running Python", sys.version.split()[0])
print("Inside a virtual environment:", in_venv)

Inside an activated environment the second line prints True. From the terminal, where python (Windows) or which python (Linux and macOS) shows which interpreter will run; the first result should be inside your .venv folder.

Installing Packages with pip

With the environment active, pip installs into it:

In a terminal:

(.venv) $ python -m pip install --upgrade pip
(.venv) $ pip install requests pandas
(.venv) $ pip install "flask==3.0.3"
(.venv) $ pip list
  • pip install name installs the latest version; name==1.2.3 installs an exact version.
  • pip list shows everything installed in this environment.
  • pip uninstall name removes a package.
  • Running pip as python -m pip guarantees you use the pip that belongs to the Python you expect.

Recording Dependencies with requirements.txt

To let anyone recreate your environment, save the exact versions installed:

In a terminal:

(.venv) $ pip freeze > requirements.txt

The file lists one package per line with its version, for example:

# requirements.txt (example)
# certifi==2024.8.30
# requests==2.32.3
# pandas==2.2.3

(In a real file the lines don't start with #; they are commented here only to show the format.) Someone else, or you on a new computer, recreates the environment with:

In a terminal:

$ python -m venv .venv
$ source .venv/bin/activate        # or the Windows command
(.venv) $ pip install -r requirements.txt

pip freeze lists every installed package, including the dependencies of your dependencies. Some developers prefer to keep a short hand-written requirements.txt with only the packages they import directly, sometimes with flexible versions such as requests>=2.31, and use a separate "lock" file for exact versions. Tools such as pip-tools, Poetry and uv automate this.

What to Commit to Git

  • Do commit requirements.txt (or pyproject.toml): it is small and describes the environment.
  • Don't commit the .venv folder. It is large, contains files specific to your operating system and Python version, and can always be rebuilt. Add .venv/ to your .gitignore file.

Common Problems and Fixes

  • "ModuleNotFoundError" even though you installed the package: you probably installed it into a different Python. Activate the environment, then run python -m pip install again, and make sure your editor uses the same interpreter.
  • The environment stopped working after moving the folder or upgrading Python: environments contain absolute paths. Delete .venv and recreate it from requirements.txt.
  • Jupyter notebooks can't see your packages: install ipykernel in the environment and select it as the notebook's kernel.
  • Different Python versions: a venv uses whichever Python created it. To use Python 3.12 specifically, create it with that interpreter, for example py -3.12 -m venv .venv on Windows.

A Typical Workflow

  1. Create the project folder and run python -m venv .venv.
  2. Activate it and upgrade pip.
  3. Install the packages you need as you go.
  4. Run pip freeze > requirements.txt whenever you add or upgrade a package.
  5. Add .venv/ to .gitignore, and commit requirements.txt with your code.
  6. Include setup instructions in your README so others can run the project in minutes.

Summary

  • Python virtual environments give each project its own isolated set of packages.
  • Create one with python -m venv .venv; activate it with .venv\Scripts\activate on Windows or source .venv/bin/activate elsewhere.
  • sys.prefix != sys.base_prefix is True inside a virtual environment.
  • Record versions with pip freeze > requirements.txt and restore them with pip install -r requirements.txt.
  • Commit the requirements file, not the .venv folder.

Related Tutorials