Python API

What it is

The torch Python package: the surface most users see. It is a mix of:

• Generated bindings — most torch.add, torch.mm, Tensor.method calls go through C++ bindings produced by torchgen.
• Pure-Python modules — torch.nn, torch.optim, torch.func, torch.distributions, torch.distributed, much of torch._dynamo, etc.
• Compiled extension (torch._C) — the underlying CPython extension that exposes the C++ side.

Top-level surface

A simplified outline:

torch
  ├── tensor / dtype / device / layout factories
  ├── creation: zeros, ones, empty, randn, arange, ...
  ├── ops: add, mm, matmul, sin, cos, sum, mean, ...
  ├── nn        — neural network modules (separate page)
  ├── optim     — optimizers (separate page)
  ├── func      — function transforms (separate page)
  ├── linalg    — numerical linalg (separate page)
  ├── fft       — FFT
  ├── special   — special functions (gamma, digamma, ...)
  ├── distributions — probability distributions
  ├── distributed   — distributed training
  ├── compile / _dynamo / _inductor / _functorch
  ├── export
  ├── jit
  ├── onnx
  ├── package
  ├── profiler
  ├── ao        — quantization, sparsity, pruning
  ├── multiprocessing — tensor-aware multiprocessing
  ├── cuda / mps / xpu / mtia
  ├── backends.{cuda,cudnn,mkldnn,mps,opt_einsum,quantized,...}
  ├── utils.data    — DataLoader
  ├── utils.checkpoint  — activation checkpointing
  ├── utils.cpp_extension — JIT C++/CUDA extensions
  ├── library      — register custom ops
  ├── overrides    — __torch_function__ machinery
  ├── testing      — utilities for tests
  └── _C           — the compiled extension

Stability

The PyTorch project's API stability policy treats:

• Public Python APIs (torch.* not starting with _) — covered by deprecation policy. Breakage requires a deprecation cycle.
• Underscored APIs (torch._*) — internal. May change without notice. The compile stack lives mostly under torch._dynamo/torch._inductor/torch._functorch precisely so that it can iterate.
• C++ APIs — torch:: namespace under torch/csrc/api/ is the supported C++ frontend.
• Internal C++ — aten/src/ATen/, c10/, anything else under torch/csrc/ is not part of the supported C++ API.

The test/test_public_bindings.py test enforces that no underscored entries leak into the public list, gated by test/allowlist_for_publicAPI.json.

How methods are added

Most Tensor.method calls dispatch through the same op machinery as torch.func calls. The Python binding code in torch/csrc/autograd/generated/python_*.cpp (codegen output) parses the args, looks up the op in the dispatcher, and calls it.

The reverse — adding a Tensor.method — is automatic for ops declared with variants: function, method in aten/src/ATen/native/native_functions.yaml.

torch._C

The CPython extension module compiled from torch/csrc/. Exposes:

• torch._C._TensorBase — the C++ Tensor type.
• torch._C._Storage — the Storage type.
• torch._C._dispatch_* — dispatcher introspection.
• torch._C._jit_* — JIT internals.
• torch._C._dynamo, torch._C._distributed_c10d, etc.

These are private but heavily used by the rest of torch. A user typically doesn't import them directly.

Type stubs

PyTorch ships type stubs (*.pyi) generated by tools/pyi/gen_pyi.py for the methods that come from C++. They keep IDE autocompletion and mypy happy. pyrefly.toml and mypy.ini configure the type checker.

Where to look

File	Purpose
torch/__init__.py (~111K lines)	Top-level surface, glue
torch/_C/__init__.pyi	Type stubs for C++ side
torch/overrides.py	Public list of overrideable functions
tools/pyi/gen_pyi.py	Type stub generator
test/test_public_bindings.py	Public surface enforcement
test/allowlist_for_publicAPI.json	Allowlist