C-API stable

Active contributors: janeyx99, mikaylagawarecki

What it is

A small ABI-stable C surface for out-of-tree extensions. The traditional torch:: C++ API is not ABI-stable; symbols can move between PyTorch versions and require recompiling against the matching headers. The stable C API gives extension authors a way to write code that survives minor PyTorch upgrades without recompilation.

The stable API is intentionally narrow — it covers the most common operations needed by custom-op extensions, not the full ATen surface.

Layout

Path	Contents
torch/csrc/stable/	Stable C API headers and shim implementation
torch/headeronly/	Header-only types safe for stable-ABI use
torch/header_only_apis.txt	The list of header-only APIs that are part of the stable surface
torch/csrc/shim_common.cpp	C-shim implementations

What's covered

The stable API includes:

• A C handle type for tensors (AtenTensorHandle) plus accessors for shape, dtype, device, data pointer, etc.
• Operator dispatch through opaque op handles (looked up by name).
• A small allocator interface.
• Header-only utilities: c10::ArrayRef, c10::optional, scalar types, dtype enums, and the float8/half number types.

What's not covered: the full ATen op set as direct C functions, autograd internals, JIT IR, distributed collectives.

How to use it

The recommended pattern is to register your custom op via TORCH_LIBRARY and have the kernel implementation use only stable-API calls. Then your shared library can be built once and loaded against multiple PyTorch versions.

The torch/headeronly/ directory has a few hundred lines of declarations marked safe for inclusion. The list is enforced by torch/header_only_apis.txt and a CI test that fails when an unsafe type leaks in.

Where it's used

• ExecuTorch's PyTorch host-side bindings.
• Some Meta-internal accelerator extensions that ship as .sos alongside their model.
• Third-party kernels (FlashAttention, Liger, …) that want a single binary across PyTorch versions.

Where to read next

• Features / Custom ops and extensions — full extension story.
• API / C++ API — the unstable but more capable surface.