Installing PyTorch and the Eager Mental Model

PyTorch descends from Torch7, a Lua framework. Facebook AI Research rebuilt the frontend in Python with tape-based autograd and released it in January 2017; 1.0 (December 2018) added TorchScript; 2.0 (March 2023) added torch.compile (Ansel et al., "PyTorch 2", ASPLOS 2024). Since 2022 the PyTorch Foundation, under the Linux Foundation, governs it. The design paper (Paszke et al., arXiv 1912.01703) opens: "Deep learning frameworks have often focused on either usability or speed, but not both." Its answer: the program is the Python code, and speed comes from a small C++ core (c10 for tensor and device primitives, ATen for operators) that each Python call drops into quickly.

The TensorFlow note covers the static-graph lineage.

The same version is built against several accelerator stacks, and the stack is part of the binary. The previous-versions page (living page, accessed 2026-10-10) lists these commands for v2.8.0; the install selector now shows a newer release.

The +cu128 suffix is a PEP 440 local version label, so torch==2.8.0 matches every row, and pip happily keeps a +cpu build on a GPU machine. Plain PyPI wheels carry no label; on Linux x86_64 the 2.8.0 PyPI wheel depends on nvidia-cuda-runtime-cu12==12.8.90 and triton==3.4.0 (PyPI metadata), so it is a CUDA 12.8 build. macOS and Windows PyPI wheels are CPU-only, with MPS included on macOS arm64.

Driver vs toolkit. CUDA wheels bundle the runtime, cuBLAS, cuDNN and NCCL as nvidia-* pip packages, so you do not need the CUDA toolkit (nvcc) unless you build extensions (module 25). You do need a new-enough driver: the "CUDA Version" printed by nvidia-smi is the newest runtime the driver supports and should be at least the wheel's. CUDA 12's minor-version compatibility lets some older 12.x drivers work, with caveats; do not plan around it. The v2.8.0 release notes also drop Maxwell and Pascal (sm50–sm60) from the 12.8 and 12.9 builds; those GPUs need cu126.

ROCm reuses the CUDA Python API: the HIP notes say "'rocm' or 'hip' are not valid, use 'cuda'", so torch.cuda.is_available() is the check and torch.version.hip tells you which stack you have. Apple silicon uses the mps device, which needs macOS 12.3+ (MPS notes). Intel GPUs need the Intel GPU driver first, then the xpu wheel (XPU getting started).

# pip, CUDA 12.8 build
python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu128

# uv, CPU build into the active environment
uv pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu

# conda/mamba: create the env with conda, install torch with pip inside it
conda create -n pt28 python=3.11 && conda activate pt28
python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu128

--index-url replaces PyPI; --extra-index-url adds the PyTorch index beside it, and then pip may pick the PyPI build. In uv projects, declare the index with explicit = true so only torch resolves from it (uv PyTorch guide). PyTorch 2.5 was the last release on the official pytorch conda channel (pytorch#138506), so conda install pytorch -c pytorch cannot give you 2.8: use pip inside conda, and never install torch with both.

On Windows, use 64-bit Python. The Windows notes cover the two usual failures: DLL load failed (missing Visual C++ redistributable) and a multiprocessing RuntimeError when a script that starts workers lacks the if __name__ == '__main__': guard, because Windows spawns rather than forks (module 14).

Ask the interpreter you will actually run, not the install log:

python -c "
import torch
print('version     ', torch.__version__)
print('cuda runtime', torch.version.cuda, '| hip', torch.version.hip)
print('cuda avail  ', torch.cuda.is_available())
print('mps avail   ', torch.backends.mps.is_available())
print('accelerator ', torch.accelerator.is_available(), torch.accelerator.current_accelerator())
print('threads     ', torch.get_num_threads())
print(torch.__config__.show())
print(torch.__config__.parallel_info())
"

On the course's reference machine (Apple M2 Pro) this printed 2.8.0, CUDA and HIP None, MPS available, accelerator True mps, and 6 threads on a 10-core chip. show() reported CPU capability usage: NO AVX (correct on arm64, which vectorises with NEON), BLAS_INFO=accelerate and USE_CUDA=OFF; parallel_info() reported ATen parallel backend: OpenMP.

For bug reports, run python -m torch.utils.collect_env.

Minor releases arrive roughly quarterly. The release cadence table in RELEASE.md at v2.8.0 planned 2.8 for July 2025 ("Patch Releases are optional"); the v2.8.0 tag and PyPI wheels shipped on 6 August 2025. Newer releases exist; this course does not track them.

The classification post defines stable (breaking changes only "with notice given one release ahead of time"), beta ("not committing to Backwards Compatibility") and prototype (shipped for feedback; may be dropped). The 2.8 release blog files new features under "API-Unstable": usable, but expect edits on upgrade. The release notes also say "torch.ao.quantization is deprecated and will be removed in 2.10" (module 29), and the ONNX exporter's default moves from TorchScript to torch.export in 2.9 (module 28).

Three compatibility layers. The BC policy covers the Python API only. A pure-Python dependency written against 2.7 usually keeps working on 2.8 unless it calls something removed or changed (a deprecation warning is the early signal). Compiled extensions are different: anything that links libtorch (torchvision's C++ ops, flash-attn, xformers, your own cpp_extension build) uses the C++ ABI, which is not stable across minor releases, so a .so built for 2.7 typically fails at import with undefined symbol or, worse, loads and crashes. That is why the torchvision 0.23.0 wheel declares torch==2.8.0 exactly (PyPI metadata). Custom ops registered through torch.library fail the same way when their compiled kernels mismatch, and their Python registrations can also collide or change schema. 2.8 ships a limited stable C++ surface (torch::stable::Tensor, listed as Unstable in the release notes) aimed at extensions that survive upgrades; module 25 covers building ops. Detect mismatches with pip check, an import smoke test of every compiled dependency in CI, and python -m torch.utils.collect_env. TorchScript, the 1.x deployment path, is legacy (the pinned C++ export tutorial calls it deprecated); new deployment work goes through torch.export (module 28).

This course pins torch==2.8.0 because its assertions are about exact behaviour: grad_fn names, what torch.export emits, defaults, deprecation warnings. Read the matching docs at https://docs.pytorch.org/docs/2.8/, never stable/, which changes under you.

Three lines, narrated:

x = torch.randn(3, 4)                       # factory kernel runs now; x owns 12 floats
w = torch.randn(4, 2, requires_grad=True)   # a leaf that autograd will track
y = (x @ w).relu()                          # aten::mm runs, then aten::relu; y is (3, 2)
print(y.grad_fn, y.grad_fn.next_functions)  # ReluBackward0 -> ((MmBackward0, 0),)

Each call crosses into C++, where the dispatcher reads the inputs' dispatch keys (autograd needed? autocast active? which device?) and routes to a kernel. Because w requires grad, the autograd layer attaches a backward node to the output as grad_fn. When y comes back it is a finished tensor.

Three consequences follow.

Debugging is ordinary Python. A shape bug fails on the line that has it; print(t.shape) and pdb work mid-forward (module 18).

Control flow is plain Python. if, while and early returns just work, and the graph contains only the branch that ran: "define-by-run", a fresh graph per forward pass. It is also why the FAQ warns "Don't accumulate history across your training loop": summing a loss that requires grad keeps every iteration's graph alive.

Every op pays fixed overhead. One local PyTorch 2.8 CPU run on an Apple M2 Pro (4 threads, torch.utils.benchmark) measured:

Up to thousands of elements the cost is dispatch, not arithmetic, so many tiny ops are overhead-bound (modules 20, 21, 23).

On CUDA, an op call enqueues a kernel on a stream and returns before the GPU finishes. Anything that needs the value (.item(), print, bool(t), .cpu()) blocks until the queue drains, and timing without torch.cuda.synchronize() measures the enqueue. This follows the CUDA semantics notes and is not executed here; module 20 covers streams.

PyTorch 2 kept eager and added other ways to run the same model:

Compiled and exported programs must compute what eager computes, up to floating-point reassociation. That is why eager comes first: a compiler bug is, by definition, a difference from eager.

torch.hub.load downloads a repository and executes its hubconf.py; the hub docs add trust_repo so "users only run code from repos that they trust". The companion Transformers course covers the architecture the capstone builds.

The course has one environment and two CI commands. From the repository root:

python -m venv .venv-pytorch
.venv-pytorch/bin/python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
.venv-pytorch/bin/python -m pip install numpy==1.26.4
.venv-pytorch/bin/python site/test_pytorch_course.py
.venv-pytorch/bin/python -m unittest discover -s site -p "test_pytorch_[0-9]*.py"

There are three kinds of fence. A plain python fence is a teaching fragment, never executed, and may use CUDA or Triton. A python pytorch-check fence is a self-contained CPU program run by site/test_pytorch_course.py: it seeds any randomness, asserts its own numbers, ends with one print, restores global state, and uses no network. A bash fence is a command for you.

Labs are scripts under code/ with a fixed contract: a docstring with the run command, argparse with --seed and --json-out, and main(argv=None) -> dict returning JSON-serialisable results. Each has a site/test_pytorch_NN_*.py unittest asserting contracts and quality bars, never one machine's loss or timing.

A passing check proves a contract on CPU with PyTorch 2.8.0: a gradient matches, an exported graph equals eager, a resume is bit-exact. It does not prove GPU speed, multi-GPU behaviour, or numerics on other hardware; GPU behaviour is described from pinned docs and labelled not executed. The default Inductor backend needs a C++ toolchain and failed on the reference Mac during course probing, so checks use backend="eager" or "aot_eager": graph capture, no code generation.

Tested with Python 3.11 and PyTorch 2.8.0 on CPU.

Orientation only: each comment names the module that explains the line.

import torch, torch.nn as nn

t = torch.arange(6.0).reshape(2, 3)              # 02 creation, 03 strides/views
a = torch.tensor(3.0, requires_grad=True)
(a ** 2).backward(); print(a.grad)               # 07 autograd: tensor(6.)

layer = nn.Linear(3, 2)                          # 10 nn.Module, 11 layers
opt = torch.optim.SGD(layer.parameters(), lr=0.1)  # 15 optimizers
loss = layer(t).pow(2).mean()                    # 13 losses
loss.backward(); opt.step(); opt.zero_grad()     # 16 the training loop

fast = torch.compile(layer, backend="eager")     # 23 torch.compile
ep = torch.export.export(layer, (t,))            # 28 export

Environment facts. This proves the interpreter imports a 2.x torch with default dtype torch.float32, introspectable build configuration and a CPU device. It does not assert 2.8.0: CI pins the version at install time, and the check stays version-agnostic.

import torch

assert torch.__version__.startswith("2."), torch.__version__
assert torch.get_default_dtype() is torch.float32
config = torch.__config__.show()
assert isinstance(config, str) and "PyTorch built with" in config
assert torch.device("cpu").type == "cpu"
assert torch.zeros(2, 3).device.type == "cpu"
first = torch.__config__.parallel_info().splitlines()[0]
print(torch.__version__, "|", first)

Eager is immediate and define-by-run. The loop runs a data-dependent number of times because while calls bool() on a real comparison. The check proves the graph holds exactly one MulBackward0 per iteration that ran, ending at the leaf's AccumulateGrad, and that the gradient is \(2^k\); two starting points give two graphs from one piece of code. It proves nothing about speed, and on CUDA that bool() would be a synchronisation point.

import torch

def double_until(x, limit=10.0):
    steps = 0
    while x.norm() < limit:          # Python control flow on a tensor value
        x = x * 2
        steps += 1
    return x, steps

def mul_chain(node):
    count = 0
    while node is not None and type(node).__name__ == "MulBackward0":
        count += 1
        node = node.next_functions[0][0]
    return count, type(node).__name__

seen = []
for start in ([0.3, 0.4], [0.03, 0.04]):        # norms 0.5 and 0.05
    a = torch.tensor(start, requires_grad=True)
    y, k = double_until(a)
    count, tail = mul_chain(y.grad_fn)
    assert count == k and tail == "AccumulateGrad", (count, k, tail)
    y.sum().backward()
    torch.testing.assert_close(a.grad, torch.full_like(a, 2.0 ** k))
    seen.append(k)
assert seen == [5, 8], seen
print("iterations per start:", seen, "graph length tracks the loop")

Compilers preserve eager semantics. A function compiled with backend="eager" (Dynamo captures the graph, eager kernels run it) and a module captured by torch.export.export must both match eager, and the exported graph must be three ATen calls (linear, gelu, linear). This proves faithful capture for these programs, not Inductor codegen or speed. Locally the first torch.compile in a process paid about 0.6 s of one-time imports; a warm rerun took about 20 ms.

import torch
import torch.nn as nn

torch._dynamo.reset()
try:
    torch.manual_seed(0)
    x = torch.randn(4, 3)

    def f(t):
        return torch.sin(t) * 2 + t.relu()

    compiled = torch.compile(f, backend="eager")
    torch.testing.assert_close(compiled(x), f(x), atol=0.0, rtol=0.0)

    model = nn.Sequential(nn.Linear(3, 5), nn.GELU(), nn.Linear(5, 2)).eval()
    ep = torch.export.export(model, (x,))
    calls = [str(n.target) for n in ep.graph.nodes if n.op == "call_function"]
    assert calls == ["aten.linear.default", "aten.gelu.default", "aten.linear.default"], calls
    with torch.no_grad():
        torch.testing.assert_close(ep.module()(x), model(x), atol=1e-6, rtol=1e-5)
finally:
    torch._dynamo.reset()
print("compile(eager) and export match eager; exported ops:", len(calls))