Python Package Management

Python Package Management: Virtual Environments and pyproject.toml

Modern Python package management relies on isolated virtual environments (venv) and standard pyproject.toml project manifests. Isolating each project prevents a library upgrade in Project A from breaking dependencies in Project B.

Python's built-in venv module creates an isolated folder holding its own Python binary and site-packages directory with zero extra tools required.

Creating and Activating a Virtual Environment

Create the environment inside your project root (conventionally named .venv), activate it in your shell, and install packages safely inside it.

# Create virtual environment
python -m venv .venv

# Activate on Windows PowerShell
.venv\Scripts\Activate.ps1

# Activate on macOS / Linux
source .venv/bin/activate

# Install inside the isolated environment
python -m pip install fastapi uvicorn

Once activated, your terminal prompt shows (.venv) and python resolves directly to .venv.

Defining Dependencies in pyproject.toml

Modern Python projects follow PEP 621 and declare metadata and dependencies inside pyproject.toml rather than legacy setup.py scripts.

[project]
name = "invoice-cli"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.27,<1.0",
    "pydantic>=2.8",
]

Common Mistakes to Avoid

• Committing .venv/ to Git: Virtual environments contain thousands of platform-specific binaries; always add .venv/ to .gitignore.
• Installing packages without activating .venv: Check which python (or Get-Command python on Windows) if an import fails right after pip install.
• Unpinned production dependencies: Use a lockfile or pip freeze > requirements.lock so production deploys install tested exact versions.

Frequently Asked Questions

What is a Python Wheel (.whl) file?

A Wheel is a pre-built binary package archive that pip extracts directly into site-packages in seconds, avoiding slow C compilation during installation.

How do I exit an active virtual environment?

Type deactivate in your terminal to restore your default system shell path.

How do venv, pipx, and uv differ?

venv isolates project libraries, pipx installs global CLI apps (like black or ruff) in separate sandboxes, and uv is a fast Rust-based replacement for pip and venv.