Getting started

This page covers building PyTorch from source, running the test suite, and finding your way around for a first contribution. The user-facing install path (a pre-built wheel from pip install torch) is documented at https://pytorch.org/get-started/locally/; this page is for working on PyTorch.

Prerequisites

Per README.md:

• Python 3.10 or later.
• A C++20 compiler — gcc >= 11.3.0 on Linux, recent clang on macOS, MSVC Build Tools on Windows.
• At least 10 GB of free disk space and 30–60 minutes for the initial build.
• For CUDA builds: CUDA toolkit, cuDNN, optionally NCCL and the matching driver. See README.md for the per-version support matrix.
• For ROCm builds: ROCm 6.4+. For Intel GPU builds: oneAPI base toolkit; see cmake/External/.

Cloning

git clone --recursive https://github.com/pytorch/pytorch
cd pytorch
git submodule sync
git submodule update --init --recursive

git submodule update --init --recursive is mandatory: PyTorch pulls a large set of submodules under third_party/ (sleef, fbgemm, kineto, cutlass, eigen, googletest, fmt, …) and the build will fail without them.

Building

The repo's CLAUDE.md and AGENTS.md make the canonical build command explicit:

pip install -e . -v --no-build-isolation

This runs setup.py, which drives CMake, builds C++/CUDA via Ninja, runs the torchgen code generator, and installs the resulting Python package in editable mode. The note in CLAUDE.md ("You should NEVER run any other command to build PyTorch") is the convention for contributors — do not call python setup.py install or cmake manually.

Common environment variables that change the build:

Variable	Effect
USE_CUDA=0	CPU-only build (much faster).
USE_DISTRIBUTED=0	Skip building torch.distributed C++ bits.
MAX_JOBS=N	Limit parallel build jobs.
DEBUG=1	Build with debug symbols.
REL_WITH_DEB_INFO=1	Release build with debug info.
BUILD_TEST=0	Skip C++ test binaries.
USE_NCCL=0	Skip NCCL.
TORCH_CUDA_ARCH_LIST	Compile only specific compute capabilities (e.g., 8.0;9.0).
CMAKE_BUILD_PARALLEL_LEVEL	Parallelism for CMake.

The full list lives in setup.py and CMakeLists.txt. For an exhaustive walk-through see README.md ("From Source").

Running tests

The test/ directory holds the Python test suite (1000+ files). The canonical runner is:

python test/run_test.py             # default subset
python test/run_test.py -i test_torch test_nn   # specific modules
python test/test_torch.py -v        # direct invocation
pytest test/test_torch.py -k matmul # pytest also works

Per CLAUDE.md's "Testing" section, contributors should write tests using PyTorch's own harness:

from torch.testing._internal.common_utils import run_tests, TestCase

class TestFeature(TestCase):
    ...

if __name__ == "__main__":
    run_tests()

Use assertEqual for tensor comparisons, @parametrize for parameter sweeps, and instantiate_device_type_tests for tests that should run across CPU/CUDA/MPS/etc. Common harness code is in torch/testing/_internal/common_utils.py and common_device_type.py.

C++ unit tests (under aten/src/ATen/test/ and c10/test/) are built when BUILD_TEST=1 (the default) and run as separate gtest binaries from build/bin/.

Linting

Per CLAUDE.md, lint is run through spin:

spin lint        # run all lints
spin fixlint     # apply autofixes
spin help        # discover commands

Under the hood spin shells out to lintrunner (configured by .lintrunner.toml), which runs clang-tidy, clang-format, ruff, mypy, flake8, and dozens of custom checks.

Building documentation

cd docs
pip install -r requirements.txt
make html

Output lands in docs/build/html/. See docs/README.md for the full doc-build flow.

A first contribution

Per CONTRIBUTING.md (a 60K-line document), the typical contribution flow is:

1. Fork and clone the repo.
2. Pick a "good first issue" from https://github.com/pytorch/pytorch/issues labelled module: ... and triaged.
3. Make changes locally; write tests in test/.
4. Run lint and a relevant test subset.
5. Open a PR; mark a draft until ready.
6. CI runs across many platforms (Linux, Windows, macOS, ROCm, CUDA, MPS, XPU); look for green checks.
7. A reviewer from CODEOWNERS will be tagged; iterate.
8. On approval, the merge bot lands the change once trunk CI is green.

ghstack is widely used inside Meta and is documented in CLAUDE.md. Ordinary external contributors can use the regular GitHub PR flow.

For the full development workflow including CI tags, retries, reverts, and module ownership see How to contribute / development workflow. For testing patterns see How to contribute / testing.