PyTorch/XLA announces its own replacement and still documents two ABI eras

The page opens by saying the project will be replaced

The first element of the file is a note block, and it is about the project's future rather than its usage. Dated 4/22/2026, it points to a TorchTPU announcement and states that once TorchTPU is public it will replace PyTorch/XLA. Above it in the same block, a note dated 10/2025 records that a more native direction for PyTorch on TPU has been proposed as an RFC, with issue 9684 open for comment. The repository is not archived, and the last commit on master is dated 2026-05-27, but the most recent published release is v2.9.0 from 2025-11-17, with v2.8.0 in August 2025 and v2.7.0 in April 2025 before it. So the code moved for months after the last tag, and the direction the maintainers chose is a different project.

Four Python version ranges, none of them the same

The Python support story is told four separate times and the four answers differ. The stable install section says builds are available for Python 3.8 to 3.11 and asks you to use one of the supported versions. A note dated 07/16/2025 says that from the 2.8 release onward, nightly and release wheels will be provided for Python 3.11 to 3.13. The package metadata declares requires-python as 3.10 or newer and lists classifiers for 3.10, 3.11 and 3.12, stopping short of both ends of the other ranges. The tree then settles the matter by carrying six lock files, one each for Python 3.8, 3.9, 3.10, 3.11, 3.12 and 3.13, alongside a requirements.in. Pick the range that matches the wheel you actually download rather than the sentence above it.

The quick start installs 2.8.0 while 2.9.0 is published

The stable install line pins both halves of the stack to the same release.

pip install torch==2.8.0 'torch_xla[tpu]==2.8.0'

That is a deliberate pairing, and it is the right shape, since the bridge and the framework are expected to move together. The problem is the version. v2.9.0 has been published since 2025-11-17, so following the documented command installs the previous minor release. The nightly block underneath has the mirror-image problem: the comment tells you to edit cp310-cp310 to fit your Python version, while the URL on the very next line is already cp312-cp312. Anyone who follows the comment literally downgrades the wheel they just asked for.

pip install 'torch_xla[tpu] @ https://storage.googleapis.com/pytorch-xla-releases/wheels/tpuvm/torch_xla-2.9.0.dev-cp312-cp312-linux_x86_64.whl' \
  -f https://storage.googleapis.com/libtpu-wheels/index.html

One section keeps the pre-C++11 instructions for a release that dropped them

The C++11 ABI section contradicts itself across three paragraphs. The first says that as of 03/18/2025, starting from the 2.7 release, C++11 ABI builds are the default and wheels built with pre-C++11 ABI are no longer provided. The next paragraph is written in a different tense about a different release: in PyTorch/XLA 2.6, wheels and docker images will be built in two ABI flavors, with pre-C++11 as the default to align with PyTorch upstream and C++11 offered for better lazy tensor tracing performance. Everything concrete below that paragraph belongs to 2.6, including the wheel names and the docker tag r2.6.0_3.10_tpuvm_cxx11.

3.9: https://storage.googleapis.com/pytorch-xla-releases/wheels/tpuvm/torch_xla-2.6.0%2Bcxx11-cp39-cp39-manylinux_2_28_x86_64.whl
3.10: https://storage.googleapis.com/pytorch-xla-releases/wheels/tpuvm/torch_xla-2.6.0%2Bcxx11-cp310-cp310-manylinux_2_28_x86_64.whl
3.11: https://storage.googleapis.com/pytorch-xla-releases/wheels/tpuvm/torch_xla-2.6.0%2Bcxx11-cp311-cp311-manylinux_2_28_x86_64.whl

The only benchmark on the page is also from that era: Mixtral 8x7B on v5p-256 at global batch size 1024, reported as 33 percent MFU for pre-C++11 ABI and 39 percent for C++ ABI.

The ABI is inferred from whatever torch build you already have

The build script exposes the ABI as an inferred value rather than a declared one. The CXX_ABI variable takes a value for the cxx_abi flag, and when it is left empty the value is inferred from torch._C, which is the installed framework's own extension module. That is the mechanism behind the pairing requirement: a wheel built one way and a framework built the other disagree at the C++ boundary, and nothing in the install step reconciles them. The same header documents twelve other switches, including BUNDLE_LIBTPU to include libtpu in the final wheel, TPUVM_MODE for a TPU build, BUILD_CPP_TESTS, a disk cache path that the comment notes leaves the build without local caching when empty, and GCLOUD_SERVICE_KEY_FILE, described as a file containing auth tokens for the remote cache and build, which implies the remote cache. TORCH_XLA_VERSION overrides the version hard-coded in the file, TORCH_XLA_PACKAGE_NAME renames the package away from torch_xla, GIT_VERSIONED_XLA_BUILD produces a git versioned build, and XLA_CPU_USE_ACL and SILO_NAME cover the CPU backend and the remote cache silo.

The single-process diff does not line up with itself

The migration example is a unified diff, and the indentation inside it does not agree with the context lines. The step wrapper is added at one level, the following context line sits at another, and the added line that moves inputs and labels onto the device is indented further than the line it is meant to sit beside. Applied literally, the result will not run. The surrounding prose carries two typos, asking you to update your exisitng training loop and commenting that you should move the model paramters to your XLA device. The multi-process diff that follows starts by removing an import of torch.multiprocessing and adding torch_xla, then breaks off at a line reading only +import. Between them the two diffs are the only code a newcomer is shown, and the shape of the change, wrapping the training loop in torch_xla.step and calling torch_xla.sync afterwards, is the part worth keeping.

SPMD is named in the tutorial that leaves it out

The getting started page introduces two modes and mentions a third. Single process means one Python interpreter controlling a single TPU at a time. Multi process means N interpreters for the N TPUs found on the system. SPMD is the third, where one interpreter controls all of them. The page then states that multi processing is more complex and is not compatible with SPMD, and that the tutorial does not dive into SPMD, pointing instead at a separate guide. The rest of the documentation is spread across directories rather than gathered here, covering concepts and troubleshooting, accelerator references, performance topics from AMP and DDP through Dynamo, FSDP, quantization, recompilation and SPMD, and features including distributed torch, pallas, scan and stable HLO. A separate tree holds torchax documents and examples.

The CI status line carries no status

A bold line reading Current CI status: sits near the top of the file, and the line after it is empty, with the paragraph about the package starting below. Whatever that label was meant to report is not on the page. The build infrastructure behind it is spread across several systems anyway: a .circleci directory alongside .github and a .devcontainer, plus an infra directory and a docker directory. The tree also carries a .torch_commit file, which pins the framework commit the bridge expects, an openxla_patches directory for changes against the compiler, and a codegen directory next to a CODEGEN_MIGRATION_GUIDE and an OP_LOWERING_GUIDE. One more odd corner: the pallas extra is installed from a JAX package index rather than the usual hosts, and the torchax tree is a second frontend living in the same repository. The package metadata calls itself Development Status 5 - Production/Stable and classifies the license as a BSD license read from the LICENSE file, while the repository metadata reports no license value at all. The examples directory is organised the same way the features are, with directories for data parallel, debug, eager, flash attention, FSDP, host offloading and scan, alongside decoder-only and ResNet training scripts, and a plugins directory holds a CPU PJRT plugin.

Editorial conclusion

PyTorch/XLA is a real compiler bridge with a documentation set that has not absorbed its own announcements. Read the TorchTPU note before you plan anything longer than an experiment, because the project says it will be replaced once TorchTPU is public. Pin torch and torch_xla to the same release, since the ABI is inferred from whichever torch build you have, and note that the quick start installs 2.8.0 while 2.9.0 exists. Take the Python floor from your own interpreter rather than from the page, which names four different ranges. If you hit the old pre-C++11 instructions, you are reading 2.6 documentation. And keep credentials out of the build environment, since one documented build variable expects a service key file for the remote cache.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. pytorch/xla on GitHub
4. README
5. Releases