1# Runtime Compatibility Policy 2 3This document describes the compatibility guarantees between the [PTE file 4format](https://pytorch.org/executorch/stable/pte-file-format.html) and the 5ExecuTorch runtime. 6 7> [!IMPORTANT] 8> The [canonical version of this document](https://github.com/pytorch/executorch/tree/main/runtime/COMPATIBILITY.md) 9> is in the `main` branch of the `pytorch/executorch` GitHub repo. 10 11## Backward compatibility (BC) 12 13Definition: Whether an older version of a PTE file can run on a newer version of 14the runtime. 15 16A PTE file created at a particular ExecuTorch version using stable 17(non-deprecated and non-experimental) APIs can be loaded and executed by a 18runtime built from a minimum of one following non-patch (major or minor) 19release. For example: 20 21* A PTE file created with version `1.2.0` will be compatible with version 22 `1.3.0`, and possibly more. 23* If `1.2.0` is followed by a major release, then a PTE file created with 24 version `1.2.0` will be compatible with version `2.0.0`, and possibly more. 25 26ExecuTorch minor releases happen every three months, following the PyTorch 27release cadence. This means that a PTE file will be supported for at least six 28months: the release in which it was built (three months) and the following 29release (another three months). 30 31These are minimum guarantees. We will strive to maintain compatibility for as 32long as possible, but it may depend on the features used by a particular PTE 33file: see "Feature-specific limitations" below. 34 35### Feature-specific limitations 36 37A PTE file may symbolically refer to functionality outside the file itself: 38operators or backends. These are linked directly into the runtime, and have 39their own compatibility guarantees, but must satisfy the minimum BC guarantees 40above. 41 42**Operators**: Core ATen operators must comply with the [Core ATen opset 43backward & forward compatibility 44policy](https://dev-discuss.pytorch.org/t/core-aten-opset-backward-forward-compatibility-policy/1772). 45Custom operators (that are not part of Core ATen) have no explicit guarantees, 46but the owners of those custom operators should try to provide similar 47guarantees, and clearly document them. 48 49**Backends**: A delegated payload in a PTE file must remain loadable and 50executable by its associated backend for at least the version range described 51above. Each backend may provide longer guarantees, which may be described in a 52file named `//executorch/backends/{name}/COMPATIBILITY.md`, or in a similar 53location for backends whose code lives outside the `executorch` repo. 54 55## Forward compatibility (FC) 56 57Definition: Whether a newer version of a PTE file can run on an older version of 58the runtime. 59 60ExecuTorch does not make guarantees about forward compatibility. It is possible 61for a newer PTE file to be loaded and executed by an older version of the 62runtime, but it is not guaranteed. The parameters used to generate the PTE file 63may affect this compatibility. 64