Ten years of Meta's machine-learning platform, reconstructed from the artefacts it is changed through: the PyTorch source tree at eight release tags, design records including one closed without merging, dated archive banners on nine sibling repositories, four published security advisories, five package registries, and the issues downstream maintainers filed when a capture path was deprecated under them. The pattern it exposes is a rule you can apply to any system that has to move a program from the language it was written in to the place it has to run.
A dynamic program written by people who keep changing it, and a destination where the language it is written in does not run.
State the problem without naming a framework and it stops being a machine-learning problem. You have a program in an interpreted language, authored by people whose job is to keep changing it, and you need to run that program somewhere the interpreter is unwelcome: inside a C++ service, on a phone, on an accelerator with its own compiler, in a fleet where per-request interpreter overhead is the cost line. Every design in this guide is a different answer to one question. How much of the program do you capture ahead of time, and what do you do with the part you cannot capture?
Meta has answered that question in public, repeatedly, for a decade, in a repository anyone can read. This guide reconstructs the answers from the tree rather than from the announcements, because the tree is dated and specific: a deprecation marker names the release it landed in, an archive banner names the day the owner gave up, and a package registry says exactly when the last artefact shipped. The finding that organises the rest of the page is that every layer which required the whole program to be captured before it could run has been retired or demoted, and the layers that survived are the ones that capture part of the program and hand the remainder back to Python.
The replacement for TorchScript made TorchScript's concession, in one line of code, in
public. Through PyTorch 2.7 the signature of torch.export.export read
strict: bool = True, meaning capture went through TorchDynamo and the resulting
graph was sound. In 2.8, released 6 August 2025, the same line reads
strict: bool = False. The docstring says what that costs: non-strict tracing
"will not validate some of the implicit assumptions baked into the graph", while the strict
path "will ensure the soundness of the resulting graph" but "has limited Python feature
coverage, thus you may experience more errors". The project chose coverage over soundness
for the second time in six years, and this time it wrote the trade-off into the parameter
documentation instead of the marketing.
What this guide covers. The published path from authored model to running artefact:
capture, intermediate representation, compilation, the runtimes that execute the result, the
checkpoint format, and the lifecycle of the satellite libraries around all of it, between 2016
and September 2026. What it deliberately does not cover. Meta's internal training
fleet, its accelerator hardware, its recommender serving stack, model quality, and cost.
Nothing in the corpus speaks to those, and the network policy for this session blocked the
hosts that would: pytorch.org, engineering.fb.com, every paper
repository and every talk archive refused at the egress proxy. There are no blog posts, papers
or talks in the evidence wall, which is a real limit and is stated again in the ledger.
Four layers, one of which keeps being replaced. Every box below is traceable to a file in the tree.
The shape is stable and the middle is not. Layer one is authoring, which has never moved: eager Python, evaluated line by line. Layer four is execution, where the set of targets has only grown: in-process Python, a standalone shared library, an on-device runtime, an interchange format for somebody else's engine. Layers two and three, capture and lowering, have been rebuilt three times, and each rebuild is a different position on the same trade-off.
The current capture layer is documented as two products rather than one, and the project's own
user guide states the difference plainly. On partial capture: "When torch.compile
runs into an untraceable part of a model, it will 'graph break' and fall back to running the
program in the eager Python runtime." On full capture: "torch.export aims to get
a full graph representation of a PyTorch model, so it will error out when something untraceable
is reached." That sentence pair is the architecture. Two entry points, one tolerant and one
strict, over a shared compiler stack, because no single answer survived contact with the
models people actually write.
Dynamo evaluates Python bytecode and emits a graph plus guards; where it cannot, it cuts
the graph and lets the interpreter run that region. The failure surface is not hidden: it is
enumerated, with 586 entries in graph_break_registry.json, each carrying a type,
a context, an explanation and hints.
Evidence: the registry file, the site generated from it every three minutes.
The exported program claims two invariants that TorchScript never claimed together: soundness, "a sound representation of the original program", and normalisation, "There are no Python semantics within the graph". Those two claims are what make a Python-free target possible at all, and the strict flag is what pays for the first one.
Evidence: export user guide, torch/export/__init__.py.
Checkpoints still travel in the ZIP container implemented under caffe2/serialize,
present at every release tag checked from 2.8.0 to 2.14.0 and on main. The
framework that contributed it was scheduled for removal in February 2022. The format
outlived the framework, which is why the loader, not the graph, is where the security work
landed.
Evidence: inline_container.h at v2.14.0, issue #72536.
Two details in that architecture are worth pulling out because they generalise. First, the
merge of the production framework in 2018 did not put the acquired code in a corner; it put
PyTorch's own build inside the acquired directory. caffe2/CMakeLists.txt on
main today is 2,258 lines long and contains add_subdirectory(../aten aten),
which is to say the tensor library and libtorch are built from the directory named after the
framework a 2022 issue proposed to delete. Removal stalled because it was never a deletion
problem; it was a build-graph problem, and build graphs are where architectural debt goes to
become invisible.
Second, the escape hatches are load bearing and are treated as such. RFC-0032, the proposal that made NumPy calls traceable, states the policy in one sentence: "For niche functions in NumPy that don't have a PyTorch equivalent, it's okay to graph break and still call NumPy to execute the function call." A design document that plans for the compiler to give up, and names the fallback as acceptable, is a different engineering posture from one that treats unsupported input as a bug to be closed later. The 586-entry registry and the site regenerated from it every three minutes are what that posture looks like once it reaches operations.
Each fork below is dated, each rejection has a stated reason, and each has a condition under which the rejected option is the right one for you.
torch.compile in 2.0 on 15 March 2023.. deprecated:: 2.5 in torch/jit/__init__.py with the text "TorchScript is deprecated, please use torch.compile instead"torch.cond and friendsstrict=False in torch.export.export"strict=True as the default, which it was through 2.7 on 23 April 2025strict=True, accept the rewrites, and treat every unvalidated assumption as a production incident waiting for an input distribution shift| Decision | Chosen | Rejected | Because | Evidence |
|---|---|---|---|---|
| Capture granularity | Partial, with catalogued breaks | Whole-program scripting | Coverage of real Python | deprecated:: 2.5 |
| Export soundness default | Non-strict from 2.8 | Strict default | Dynamo coverage errors on real models | 2.8.0 notes |
| Mobile runtime | ExecuTorch, 1.0 on 17 October 2025 | Lite Interpreter | "Lite Interpreter is deprecated. Please consider switching to ExecuTorch." | torch/jit/_script.py |
| Interchange exporter | Dynamo based, default from 2.9 | TorchScript based | Kept only as automatic fallback for scripted modules | issue #151693 |
| Own model server | Leave it to the ecosystem | TorchServe | Archived 7 August 2025 with no security patches promised | pytorch/serve |
| Accelerator compiler | Inductor plus Triton, in core | Glow, Tensor Comprehensions | Archived 1 July 2025 and 28 April 2023 | pytorch/glow |
| Checkpoint safety | Allowlisted unpickler by default from 2.6 | Trusting pickle, or requiring a new format | "closing the loop on the deprecation that started in 2.4" | 2.6.0 notes |
| Governance boundary | Neutral project, company libraries in a separate organisation | Vendor-controlled direction | "Technical governance is strictly separated from business governance." | governance.md |
The governance row deserves a sentence of its own, because it explains an artefact that looks
like a rebrand and is not. The in-repo governance document states that "Technical governance is
strictly separated from business governance", and answers the obvious follow-up bluntly: a
company cannot buy a board seat to drive direction, only sponsor through the PyTorch
Foundation. As of September 2026 the practical consequence is visible in the organisation
names. The neutral project lives under pytorch; Meta's own adjacent libraries,
including torchrec, monarch, torchcomms and the graph-break site, live under
meta-pytorch, and torchtune's issue tracker now resolves there. Neither
organisation page says when the split happened, and I found no primary artefact that dates it,
so treat the boundary as observed and the timing as open.
One rejected design is worth reading in full if you ever propose an abstraction to a platform team. RFC-0009, the DataLoader architecture proposal, opened on 29 January 2021 and closed unmerged on 7 July 2022. Its problem statement is exactly right: "Users want to point PyTorch to a remote data source... and iterate over contents without downloading the entire dataset." A reviewer suggested the ecosystem already had the pieces, naming fsspec, s3fs and gcsfs. The design was never accepted, the code shipped anyway in a satellite repository as DataPipes and DataLoader2, and it was removed two and a half years later while the plain DataLoader it intended to replace is still the default. The RFC process recorded the disagreement, the satellite let the code ship without resolving it, and the registry recorded the ending.
Three failure classes: capture that regresses, a format boundary that is not a boundary, and lifecycle promises that expire. Meta publishes no incident postmortems for this platform, so the incident-grade evidence here is its own security advisories and the issues filed by downstream maintainers.
strict=False.forward can be exported.weights_only=True, loading a hostile checkpoint is safe.weights_only=True, "can corrupt memory and potentially lead to arbitrary code execution", affecting every release up to 2.9.1.Across those six entries the classes are distinct and the lesson is shared. Capture failures come from a tool's coverage of a language it does not own. Format failures come from treating a hardened parser as a trust boundary. Lifecycle failures come from depending on a layer whose existence is a strategy decision rather than a technical necessity. The transferable habit is to ask, for every dependency in a deployment path, which of those three risks you are carrying, and then to instrument the one you are carrying rather than all three.
Dates, counts and cadences, each with the artefact it came from. Every figure below was read from a file or a registry on 24 September 2026.
| Metric | Value | At | Context | As of | Source |
|---|---|---|---|---|---|
| Catalogued graph-break reasons | 586 | PyTorch main | Entries in the Dynamo registry, keys GB0000 to GB9958 | 2026-09-24 | registry file |
| Graph-break site refresh | 3 min | meta-pytorch | Cron regeneration of the public break documentation | 2026-09-24 | site README |
| Minor release cadence | ~3 months | PyTorch | 15 minor releases from 2.0.0 to 2.14.0 | 2026-09-02 | PyPI history |
| Deprecation window policy | 1 release | PyTorch OSS | "stable features will be deprecated for one release before a BC-breaking change" | 2022 | RFC-0017 |
| TorchScript deprecated in | 2.5 | PyTorch | Released 17 October 2024; marker still in the tree in 2026 | 2024-10-17 | torch/jit/__init__.py |
| Export strict default flipped | 2.8 | PyTorch | True through 2.7 (2025-04-23), False from 2.8 (2025-08-06) | 2025-08-06 | v2.8.0 source |
| Downstream reaction lag | 3 to 13 months | DJL, Lightning, MONAI | Issues filed 2024-07-18, 2025-10-16 and 2025-11-14 against a marker landed 2024-10-17 | 2025-11-14 | Lightning #21293 |
| DataPipes lifetime | 2 yr 9 mo | torchdata | 0.3.0 on 2022-03-10 to removal in 0.10.1 on 2024-12-13 | 2024-12-13 | PyPI history |
| torchdata silence since last release | 19 months | torchdata | 0.11.0 published 2025-02-20, nothing since | 2026-09-24 | PyPI history |
| ExecuTorch to 1.0 | 2 yr | ExecuTorch | 0.1.0 on 2023-10-11, 1.0.0 on 2025-10-17, 1.5.1 on 2026-09-22 | 2026-09-22 | PyPI history |
| torchtune shipping life | 12.5 months | torchtune | 0.0.1 on 2024-03-21 to 0.6.1 on 2025-04-07; wind-down announced 2025-07-15 | 2025-07-15 | issue #2883 |
| TorchServe image gap before archive | 11 months | TorchServe | Last image 2024-09-30, archived 2025-08-07 | 2025-08-07 | Docker Hub |
| Checkpoint-loader advisories | 2 of 5 | PyTorch | Published advisories concerning torch.load, out of five in total | 2026-09-24 | advisory list |
| Time from safe default to first bypass | 78 days | PyTorch | Default flipped 2025-01-29, Critical advisory 2025-04-17 | 2025-04-17 | 2.6.0 notes |
| Caffe2 removal, elapsed | 4 yr 7 mo | PyTorch | Issue opened 2022-02-08; caffe2/ still builds libtorch on main | 2026-09-24 | issue #72536 |
| Satellite repo to archive, after absorption | 1.5 to 3 yr | TorchElastic, functorch | In-tree 1.9 then archived 2023-01-06; in-tree 2022-09-21 then archived 2025-08-21 | 2025-08-21 | pytorch/functorch |
All of the above are measured from files or registry metadata, not claimed by anyone. Three are derived by arithmetic on two dated artefacts: the DataPipes lifetime, the 78 days to first bypass, and the Caffe2 elapsed figure. Four things are unknown and matter more than anything in the table: how many models inside Meta still depend on serialised TorchScript, what fraction of compiled models in production hit a graph break and how often, what the export path costs in engineer time per model family, and whether any of the archived components are still running somewhere. No public artefact answers those, and the corpus cannot be made to.
Every artefact this page rests on, graded. Filter by kind. The full ledger,
with one row per claim and the copied quote behind it, ships beside this file as
sources.md.
High severity, CVSS 8.8, affecting every release up to 2.9.1. A crafted checkpoint defeats the allowlisted unpickler through pickle opcode and storage metadata handling.
GHSA-53q9-r3pm-6pq6 (Critical, 2025-04-17) and GHSA-63cw-57p8-fm3p (2026-01-26) both
concern torch.load; the others cover a flatbuffer parser, a transitive libuv
issue and an Actions expression injection.
The same parameter, two tags apart: strict: bool = True becomes
strict: bool = False. The docstring states that the permissive default "will
not validate some of the implicit assumptions baked into the graph".
Four occurrences of ".. deprecated:: 2.5 / TorchScript is deprecated, please use
torch.compile instead", plus "Lite Interpreter is deprecated. Please consider
switching to ExecuTorch."
586 entries, each with a break type, a context template, an explanation and hints. The machine-readable inventory of everything the compiler declines to capture.
States the compatibility promises directly, including "we will not break a serialized torchscript program running in production at Meta" and a one-release OSS deprecation window.
Designs a translation layer so Dynamo can trace NumPy calls, and accepts the fallback in writing: "it's okay to graph break and still call NumPy to execute the function call".
The DataLoader redesign proposal. A reviewer pointed at fsspec, s3fs and gcsfs as the existing answer. Never merged; the code shipped in a satellite repository regardless and was removed in December 2024.
A request for a written short, medium and long-term statement on the capture stack. Closed as not planned, sixteen months before the deprecation marker appeared in the code.
"Unexpected type in sourceless builder transformers.models.bit.configuration_bit.BitConfig",
raised on a config access in forward. Passes with strict=False.
States that TorchScript is fully deprecated in 2.9, and that the replacement cannot capture
control flow the same way: only networks without control flow in forward can
currently be exported.
A training framework working out what to do with LightningModule.to_torchscript:
reimplement, deprecate, or remove and push the work onto users.
A JVM serving stack whose entire PyTorch integration is TorchScript asking what replaces it, three months before the deprecation marker landed in the code.
"This project is no longer actively maintained... there are no planned updates, bug fixes, new features, or security patches."
Active development stopped effective immediately on 15 July 2025, after 150 contributors and 21 recipes, with support limited to critical fixes during 2025.
TorchElastic 2023-01-06, Tensor Comprehensions 2023-04-28, Glow 2025-07-01, TorchServe 2025-08-07, functorch 2025-08-21, fairseq 2026-03-20, plus torchtune's wind-down, torchdata's silence and FairScale's upstreaming note.
2,258 lines, containing add_subdirectory(../aten aten). The directory named
for the framework a 2022 issue proposed to remove is where libtorch is built.
"Automatic kernel generation and graph-level transformations using torch.compile." The serving layer that replaced the first-party server is built on partial capture, not on a serialised graph.
"Technical governance is strictly separated from business governance", and a company cannot purchase a board seat to drive direction, only sponsor through the PyTorch Foundation.
Every date in this guide is checked against upload timestamps: quarterly minors since 2.0, torchdata silent since February 2025, ExecuTorch at 1.5.1, torchtune's last wheel in April 2025.
Newest tags are 0.12.0, last updated 30 September 2024, eleven months before the repository was archived.
pytorch_android and pytorch_android_lite sit beside
executorch-android, executorch-android-qnn and
executorch-android-vulkan: the mobile handover, visible as artefact names.
An executorch npm package at 0.0.7, and TorchSharp on NuGet with 64 versions
from November 2018 to 0.107.0 in May 2026: bindings track libtorch, slowly.
The primary statements of intent: the weights_only flip, the strict default
switch, the ONNX default switch, and the documented difference between partial and full
capture.
There are no engineering blogs, papers or talks above. That is not an editorial choice: the
hosts that carry them refused at this session's egress proxy, including
pytorch.org, engineering.fb.com, arxiv.org,
dl.acm.org and usenix.org. The corpus is therefore strong on dated
fact and weak on stated motive. Where motive appears in this guide it is quoted from a
docstring, a release note, an RFC or an issue, and where it is my reading, the sentence says
so.
Six rungs. The first three fit an evening; the last three are what the decade above says you will actually need.
Take a model you own with a data-dependent branch in forward. Compile it and
collect the break reports, then look each one up against the published break registry.
Done when: you can name every break by its catalogue entry and say which are in your code and which are in a library. Teaches: partial capture is a measurable property of your model, not a property of the tool.
Export with strict=True and with the 2.8 default. Record what fails, what
silently succeeds, and what the two graphs differ on.
Done when: you can state, for your model, which implicit assumptions the permissive path did not validate. Teaches: the difference between a build error now and an input-dependent failure later.
Convert the data-dependent branch to a structured control-flow operator and re-export strict. Time how long it took.
Done when: strict export passes and the numerics match eager on two input shapes. Teaches: what MONAI's issue means in hours per model, which is the real unit of a deprecation.
Take the exported program to an ahead-of-time artefact and load it from a process that never imports Python, then again for an on-device runtime.
Done when: the artefact runs with the framework uninstalled. Teaches: why full capture exists, and why every layer that demanded it was politically hard to retire.
Load a checkpoint from an untrusted source with the safe default on, then read the two loader advisories and decide whether your pipeline should accept that format at all.
Done when: your loader either rejects the executable format or documents why the risk is accepted. Teaches: a hardened parser is a mitigation with a patch cadence, not a boundary.
For each platform dependency in your deployment path, automate three signals: newest artefact in its registry, newest commit, and whether the capability exists in the component that would survive its retirement. Alert on the first two going quiet.
Done when: the check runs weekly and has flagged at least one dependency you did not know had gone quiet. Teaches: the eleven-month gap between TorchServe's last image and its archive banner, applied to your own stack.
The queries and fetch patterns that produced this page. Most of it came from reading files at tags, not from searching.
raw.githubusercontent.com/<org>/<repo>/refs/tags/<tag>/<path>grep -n "deprecated" torch/<module>/__init__.pyfor t in v2.4.0 v2.6.0 v2.8.0; do curl -s .../$t/<file> | grep "default"; donesite:github.com "was archived by the owner on" <org>"no longer actively maintained" OR "no planned updates" <project>"has been upstreamed to" OR "is in the PyTorch source tree"pypi.org/pypi/<package>/jsonhub.docker.com/v2/repositories/<org>/<image>/tags?page_size=5repo1.maven.org/maven2/<group path>/repo:<org>/rfcs is:pr is:closed is:unmerged sort:comments-descrepo:<org>/<repo> is:issue "status" OR "roadmap" closed as not planned"<deprecated feature>" deprecation -site:<vendor>.org in:titleThe tree is honest in a way the announcements are not. A default value at a tag, an archive date, and the timestamp on the last published artefact are three facts nobody wrote for an audience.
The transferable lesson of the decade, stated once: do not build a layer that requires total capture of a program you do not control. Make the capture boundary explicit, enumerate what falls outside it, and measure how often that happens in your own workload. Meta got there by elimination, retiring or demoting every component that demanded the whole program, and the two things still standing in 2026 are the tolerant path that names its 586 escapes and the strict path that is now opt-in. If your platform has a layer that keeps being rewritten, the constraint is not in that layer. It is upstream, in the programming model, and the rewrite you are planning will fail for the same reason the last two did.