Virtual Environments and pip

A Python install ships with a small standard library. Anything beyond that — NumPy, requests, Flask, pandas — comes from PyPI, the Python Package Index. You install packages with pip and you keep projects from stepping on each other's toes with virtual environments.

This page is reference material; the commands below are intended to be run in your terminal on your local machine, not in the interactive code blocks.

Why virtual environments?

Imagine you have two projects:

• Project A needs requests==2.25.1 (an old version for compatibility with legacy code).
• Project B needs requests>=2.31.0 (the latest, for new features).

Without isolation, both projects share the same site-packages directory. Installing one version breaks the other. A virtual environment solves this by creating a self-contained Python installation for each project, with its own site-packages.

Each virtual environment has its own Python interpreter copy (symlinked on Unix, copied on Windows) and its own site-packages directory. Activating a venv puts it first on your PATH, so python and pip point to that isolated environment.

Creating a virtual environment with venv

venv ships with Python 3. From any project directory:

# Create the environment in a folder called .venv
python3 -m venv .venv

This creates a .venv/ directory containing:

• A copy (or symlink) of the Python interpreter.
• A site-packages/ folder for installed packages.
• Activation scripts to modify your shell's PATH.

Activating the environment

Activation modifies your shell's PATH so python and pip point to the virtual environment:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\\Scripts\\activate.bat

# Windows (PowerShell)
.venv\\Scripts\\Activate.ps1

Your prompt will change to show the active environment:

(.venv) user@host:~/project$

Now python --version and which python (or where python on Windows) point inside .venv/.

Deactivating

When you're done:

deactivate

Your prompt returns to normal, and python points back to the system installation.

Installing packages with pip

Inside the activated environment:

pip install requests
pip install "numpy>=2.0,<3"
pip install -U requests              # upgrade to latest
pip uninstall requests
pip list                              # what is installed
pip show requests                     # details for one package

Packages are installed into .venv/site-packages/, isolated from the system and other venvs.

# Example: after 'pip install requests' in your venv
import requests

response = requests.get("https://api.github.com")
print(response.status_code)
print(response.json()["current_user_url"])

Pinning versions with requirements.txt

requirements.txt records what your project needs. Generate it from the active environment:

pip freeze > requirements.txt

This writes every installed package with an exact version:

certifi==2024.8.30
charset-normalizer==3.4.0
idna==3.10
requests==2.32.3
urllib3==2.2.3

To reproduce the environment later (on another machine, in CI, on a server):

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

.gitignore your virtual environment

Never commit a virtual environment to version control. Virtual environments are not portable across machines or operating systems. Commit requirements.txt or pyproject.toml instead.

Add to .gitignore:

.venv/
venv/
env/
*.pyc
__pycache__/

Modern alternatives: uv, poetry, hatch, pdm

The Python packaging ecosystem is rapidly improving. As of 2026, the most popular modern tools are:

uv (recommended)

uv is a Rust-based tool that replaces pip, pip-tools, and venv. It's 10–100× faster and handles Python version management too.

# Install uv (from their docs)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a venv with uv
uv venv

# Install packages
uv pip install requests

# Compile a lockfile
uv pip compile requirements.in -o requirements.txt

# Sync the venv to the lockfile
uv pip sync requirements.txt

uv is fast enough to make dependency resolution feel instant, even on large projects.

poetry

poetry combines dependency management, virtual environments, and packaging into one tool driven by pyproject.toml:

poetry init
poetry add requests
poetry install
poetry run python script.py

poetry auto-manages the venv and generates poetry.lock for reproducibility.

hatch and pdm

hatch and pdm are similar pyproject.toml-based workflows with strong plugin ecosystems.

All of these tools speak pyproject.toml, the standard project metadata file defined in PEP 621.

pyproject.toml at a glance

pyproject.toml replaces the older setup.py for the vast majority of projects. It defines project metadata, dependencies, and build configuration:

[project]
name = "my-app"
version = "0.1.0"
description = "A small Python app"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31",
    "rich>=13.0",
]

[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Most modern tools can read this file and install the listed dependencies.

Cheat sheet

Directory structure example

After creating and activating a venv, your project might look like:

my-project/
├── .venv/                  # virtual environment (in .gitignore)
│   ├── bin/                # activation scripts, python, pip
│   ├── lib/
│   │   └── python3.12/
│   │       └── site-packages/  # installed packages
│   └── pyvenv.cfg
├── src/
│   └── main.py
├── tests/
│   └── test_main.py
├── requirements.txt        # or requirements.in + requirements.txt
├── pyproject.toml          # modern projects
├── README.md
└── .gitignore              # includes .venv/

The .venv/ directory is never committed. Your teammates and CI systems recreate it from requirements.txt or pyproject.toml.

Multiple-choice questions

You now have everything you need to start writing real Python projects. The final page surveys what to learn next.