Get Started

Python Environments

Dependency hell is real. Virtual environments are the cure.

30 minutesBuildShellFree lesson

Learning Objectives

  • Create isolated virtual environments using uvvenvor conda
  • Write a pyproject.toml with optional dependency groups and generate lockfiles for reproducibility
  • Diagnose and fix common pitfalls: global installs, pip/conda mixing, CUDA version mismatches
  • Implement a per-phase environment strategy for projects with conflicting dependencies

The Problem

You install PyTorch 2.4 for a fine-tuning project. Next week, a different project needs PyTorch 2.1 because its CUDA build is pinned. You upgrade globally, and the first project breaks. You downgrade, and the second one breaks.

This is dependency hell. It happens constantly in AI/ML work because:

  • PyTorch, JAX, and TensorFlow each ship their own CUDA bindings
  • Model libraries pin specific framework versions
  • A global pip install overwrites whatever was there before
  • CUDA 11.8 builds don't work with CUDA 12.x drivers (and vice versa)

The fix: every project gets its own isolated environment with its own packages.

The Concept

Build It

Option 1: uv venv (Recommended)

uv is the fastest Python package manager (10-100x faster than pip). It handles virtual environments, Python versions, and dependency resolution in one tool.

Terminal
curl -LsSf https://astral.sh/uv/install.sh | sh

uv python install 3.12

cd your-project
uv venv
source .venv/bin/activate

Install packages:

Terminal
uv pip install torch numpy

Create a project with pyproject.toml in one step:

Terminal
uv init my-ai-project
cd my-ai-project
uv add torch numpy matplotlib

Option 2: venv (Built-in)

If you can't install uvPython ships with venv:

Terminal
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

pip install torch numpy

Slower than uvbut works everywhere Python is installed.

Option 3: conda (When You Need It)

Conda manages non-Python dependencies like CUDA toolkits, cuDNN, and C libraries. Use it when:

  • You need a specific CUDA toolkit version without installing it system-wide
  • You're on a shared cluster where you can't install system packages
  • A library's install instructions say "use conda"
Terminal
# Install miniconda (not the full Anaconda)
curl -LsSf https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -o miniconda.sh
bash miniconda.sh -b

conda create -n myproject python=3.12
conda activate myproject

conda install pytorch torchvision torchaudio pytorch-cuda=12.4 -c pytorch -c nvidia

One rule: if you use conda for an environment, use conda for all packages in that environment. Mixing pip install into a conda env causes dependency conflicts that are painful to debug.

For This Course: Per-Phase Strategy

You could create one environment for the whole course. Don't. Different phases need different (sometimes conflicting) dependencies.

Strategy:

Code
ai-engineering-from-scratch/
├── .venv/                    <-- shared lightweight env for phases 0-3
├── phases/
│   ├── 04-neural-networks/
│   │   └── .venv/            <-- PyTorch env
│   ├── 05-cnns/
│   │   └── .venv/            <-- same PyTorch env (symlink or shared)
│   ├── 08-transformers/
│   │   └── .venv/            <-- might need different transformer versions
│   └── 11-llm-apis/
│       └── .venv/            <-- API SDKs, no torch needed

The script in code/env_setup.sh creates the base environment for this course.

pyproject.toml Basics

Every Python project should have a pyproject.toml. It replaces setup.pysetup.cfgand requirements.txt in one file.

TOML
[project]
name = "ai-engineering-from-scratch"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "numpy>=1.26",
    "matplotlib>=3.8",
    "jupyter>=1.0",
    "scikit-learn>=1.4",
]

[project.optional-dependencies]
torch = ["torch>=2.3", "torchvision>=0.18"]
llm = ["anthropic>=0.39", "openai>=1.50"]

Then install:

Terminal
uv pip install -e ".[torch]"    # base + PyTorch
uv pip install -e ".[llm]"     # base + LLM SDKs
uv pip install -e ".[torch,llm]" # everything

Lockfiles

A lockfile pins every dependency (including transitive ones) to exact versions. This guarantees reproducibility: anyone who installs from the lockfile gets exactly the same packages.

Terminal
# uv generates uv.lock automatically when using uv add
uv add numpy

# pip-tools approach
uv pip compile pyproject.toml -o requirements.lock
uv pip install -r requirements.lock

Commit your lockfile to git. When someone clones the repo, they install from the lockfile and get identical versions.

Common Mistakes

1. Installing globally

Terminal
pip install torch  # BAD: installs to system Python

source .venv/bin/activate
pip install torch  # GOOD: installs to virtual environment

Check where your packages go:

Terminal
which python       # should show .venv/bin/python, not /usr/bin/python
which pip           # should show .venv/bin/pip

2. Mixing pip and conda

Terminal
conda create -n myenv python=3.12
conda activate myenv
conda install pytorch -c pytorch
pip install some-other-package   # BAD: can break conda's dependency tracking
conda install some-other-package # GOOD: let conda manage everything

If you must use pip inside conda (some packages are pip-only), install all conda packages first, then pip packages last.

3. Forgetting to activate

Terminal
python train.py           # uses system Python, missing packages
source .venv/bin/activate
python train.py           # uses project Python, packages found

Your shell prompt should show the environment name:

Code
(.venv) $ python train.py

4. Committing .venv to git

Terminal
echo ".venv/" >> .gitignore

Virtual environments are 200MB-2GB. They're local, not portable between machines. Commit pyproject.toml and the lockfile instead.

5. CUDA version mismatch

Terminal
nvidia-smi                # shows driver CUDA version (e.g., 12.4)
python -c "import torch; print(torch.version.cuda)"  # shows PyTorch CUDA version

# These must be compatible.
# PyTorch CUDA version must be <= driver CUDA version.

Use It

Run the setup script to create your course environment:

Terminal
bash phases/00-setup-and-tooling/06-python-environments/code/env_setup.sh

This creates a .venv at the repo root with core dependencies installed and verified.

Exercises

  1. Run env_setup.sh and verify all checks pass
  2. Create a second virtual environment, install a different version of numpy in it, and confirm the two environments are isolated
  3. Write a pyproject.toml for a project that needs both PyTorch and the Anthropic SDK
  4. Deliberately install a package globally (without activating a venv), notice where it goes, then uninstall it

Hints

Exercise 1. Run bash phases/00-setup-and-tooling/06-python-environments/code/env_setup.sh from the repository root. Read each line of output; when a check fails, fix that one item and run the script again until no check fails.

Exercise 2. Make the second environment in a new folder with uv venvactivate it, and install an older numpy with a version pin such as numpy==1.26.4. Run python -c "import numpy; print(numpy.__version__)" in each environment; the two versions must be different.

Exercise 3. Start from the example in pyproject.toml Basics and list torch and anthropic under dependencies. Run uv pip install -e . or uv sync in a new environment; the file is correct when both packages import without an error.

Exercise 4. Deactivate every environment, run pip install --user <small package>then run pip show <package> and read the Location line. Uninstall it with pip uninstall <package> and run pip show again to confirm that it is gone.

Key Terms

TermWhat people sayWhat it actually means
Virtual environment"A venv"An isolated directory containing a Python interpreter and packages, separate from the system Python
Lockfile"Pinned dependencies"A file listing every package and its exact version, guaranteeing identical installs across machines
pyproject.toml"The new setup.py"The standard Python project configuration file, replacing setup.py/setup.cfg/requirements.txt
Transitive dependency"A dependency of a dependency"Package B depends on C; if you install A which depends on B, C is a transitive dependency of A
CUDA mismatch"My GPU isn't working"PyTorch was compiled for a different CUDA version than what your GPU driver supports

Check what you learned

5 questions. Answer each one to see why.

Question 1 of 50 correct

What problem do virtual environments solve?

The full code

Every file for this lesson. Copy it, run it, then change it.

env_setup.sh
#!/usr/bin/env bash
set -euo pipefail

PYTHON_MIN_MAJOR=3
PYTHON_MIN_MINOR=11
VENV_DIR=".venv"
CORE_PACKAGES="numpy matplotlib jupyter scikit-learn pandas"

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

pass() { echo -e "  ${GREEN}[PASS]${NC} $1"; }
fail() { echo -e "  ${RED}[FAIL]${NC} $1"; }
warn() { echo -e "  ${YELLOW}[WARN]${NC} $1"; }

REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
cd "$REPO_ROOT"

echo ""
echo "=== AI Engineering from Scratch: Python Environment Setup ==="
echo ""
echo "Repo root: $REPO_ROOT"
echo ""

HAS_UV=false
if command -v uv &> /dev/null; then
    HAS_UV=true
    pass "uv found: $(uv --version)"
else
    warn "uv not found. Install it: curl -LsSf https://astral.sh/uv/install.sh | sh"
    warn "Falling back to python3 -m venv + pip"
fi

PYTHON_CMD=""
for cmd in python3 python; do
    if command -v "$cmd" &> /dev/null; then
        version=$("$cmd" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || true)
        if [ -n "$version" ]; then
            major=$(echo "$version" | cut -d. -f1)
            minor=$(echo "$version" | cut -d. -f2)
            if [ "$major" -ge "$PYTHON_MIN_MAJOR" ] && [ "$minor" -ge "$PYTHON_MIN_MINOR" ]; then
                PYTHON_CMD="$cmd"
                break
            fi
        fi
    fi
done

if [ -z "$PYTHON_CMD" ]; then
    fail "Python ${PYTHON_MIN_MAJOR}.${PYTHON_MIN_MINOR}+ not found"
    echo ""
    echo "Install Python ${PYTHON_MIN_MAJOR}.${PYTHON_MIN_MINOR}+:"
    echo "  uv:    uv python install 3.12"
    echo "  macOS: brew install python@3.12"
    echo "  Linux: sudo apt install python3.12 python3.12-venv"
    exit 1
fi

pass "Python: $($PYTHON_CMD --version)"

echo ""
echo "--- Creating virtual environment ---"
echo ""

if [ -d "$VENV_DIR" ]; then
    warn "Existing $VENV_DIR found. Reusing it."
else
    if $HAS_UV; then
        uv venv "$VENV_DIR"
    else
        "$PYTHON_CMD" -m venv "$VENV_DIR"
    fi
    pass "Created $VENV_DIR"
fi

if [ -f "$VENV_DIR/bin/activate" ]; then
    source "$VENV_DIR/bin/activate"
elif [ -f "$VENV_DIR/Scripts/activate" ]; then
    source "$VENV_DIR/Scripts/activate"
else
    fail "Could not find activation script in $VENV_DIR"
    exit 1
fi

pass "Activated virtual environment"

VENV_PYTHON="$(which python)"
if [[ "$VENV_PYTHON" != *"$VENV_DIR"* ]]; then
    fail "Python is not running from the venv: $VENV_PYTHON"
    exit 1
fi
pass "Python path: $VENV_PYTHON"

echo ""
echo "--- Installing core packages ---"
echo ""

if $HAS_UV; then
    uv pip install $CORE_PACKAGES
else
    pip install --upgrade pip
    pip install $CORE_PACKAGES
fi

pass "Installed: $CORE_PACKAGES"

echo ""
echo "--- Verifying installation ---"
echo ""

FAILURES=0

verify_package() {
    local pkg=$1
    local import_name=${2:-$1}
    if python -c "import $import_name; print(f'  $pkg: {${import_name}.__version__}')" 2>/dev/null; then
        return 0
    else
        fail "$pkg"
        FAILURES=$((FAILURES + 1))
        return 1
    fi
}

verify_package "numpy" "numpy"
verify_package "matplotlib" "matplotlib"
verify_package "scikit-learn" "sklearn"
verify_package "pandas" "pandas"
verify_package "jupyter" "jupyter_core"

echo ""
python -c "
import numpy as np
a = np.random.randn(3, 3)
b = np.random.randn(3, 3)
c = a @ b
print(f'  Matrix multiply check: ({a.shape}) @ ({b.shape}) = ({c.shape})')
"
pass "NumPy operations working"

echo ""
if python -c "import torch" 2>/dev/null; then
    TORCH_VERSION=$(python -c "import torch; print(torch.__version__)")
    CUDA_AVAIL=$(python -c "import torch; print(torch.cuda.is_available())")
    pass "PyTorch $TORCH_VERSION (CUDA: $CUDA_AVAIL)"
else
    warn "PyTorch not installed (install later when needed):"
    echo "    uv pip install torch torchvision torchaudio"
fi

echo ""
echo "=== Summary ==="
echo ""
echo "  Repo root:    $REPO_ROOT"
echo "  Venv:         $REPO_ROOT/$VENV_DIR"
echo "  Python:       $(python --version)"
echo "  Packages:     $CORE_PACKAGES"
echo ""

if [ "$FAILURES" -gt 0 ]; then
    fail "$FAILURES package(s) failed verification"
    exit 1
else
    pass "All checks passed"
    echo ""
    echo "Activate this environment in future sessions:"
    echo ""
    echo "  source $REPO_ROOT/$VENV_DIR/bin/activate"
    echo ""
fi