π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
API Stability Policy
====================
.. meta::
:description: What Kornia users may rely on: stable, best-effort and experimental module tiers, the deprecation policy, and how breaking changes are announced.
Kornia is depended on by a large installed base (millions of downloads per
month) and, increasingly, by language models that carry a lagging snapshot of
the API in their weights. Both are punished by silent churn. This page states
what you may rely on, per module tier, and what change looks like when it has
to happen.
Stability tiers
---------------
**Stable core** β ``kornia.geometry``, ``kornia.augmentation``,
``kornia.color``, ``kornia.filters``, ``kornia.enhance``, ``kornia.losses``,
``kornia.metrics``, ``kornia.morphology``, ``kornia.io``, ``kornia.image``,
``kornia.core``, and the classical (non-pretrained) parts of
``kornia.feature`` (e.g. detectors, descriptors, matching utilities). The
promises below apply in full.
**Best-effort** β pre-trained model wrappers (LoFTR, LightGlue, DISK, DeDoDe,
SAM, and friends in ``kornia.feature``/``kornia.models``) and ``kornia.onnx``.
These track external checkpoints, upstream repositories, and PyTorch
internals; they are kept working on currently supported PyTorch versions, but
their interfaces and weights may change with their upstreams, and they may be
frozen or split out rather than grown.
**Experimental** β ``kornia.contrib`` and anything underscore-prefixed or
absent from the rendered documentation. No stability promise.
Planned evolution: support tiers
--------------------------------
The `roadmap <https://github.com/kornia/kornia/blob/main/ROADMAP.md>`_ describes
a future, finer-grained tier structure ("Tier A / B / C") in which a deliberately
small Tier A core carries per-symbol, CI-enforced guarantees. **That structure is
not in force yet.** It will be published only after the coordinated
repair-and-deprecation window described in the roadmap has resolved the
convention bugs surfaced by the ongoing per-operator audit β targeted within the
roadmap's ~6-month medium-term horizon (dates are intentions, not commitments).
Until the tier policy is published, this page is the authoritative stability
contract and the tiers above (stable core / best-effort / experimental) are what
you may rely on.
The repair window itself runs under the promises on this page, not around them:
a deliberate change to a default or convention that works as documented gets the
promise-2 deprecation treatment β at least one minor release of warnings, landing
at a 0.x minor boundary, with old-vs-new reference vectors. A fix for a
correctness bug (NaN, a crash, wrong math, or a result that contradicts what the
operation is documented to do) uses the escape hatch below instead: it lands when
it is ready, without a warning cycle, and its release note says what the old
behavior was.
What counts as public API
-------------------------
A symbol is public when it appears in the rendered documentation at
`kornia.readthedocs.io <https://kornia.readthedocs.io/en/latest/>`_.
Underscore-prefixed modules and names, and undocumented helpers, are private
regardless of importability.
The promises (stable core)
--------------------------
1. **Deprecation before removal.** A public symbol is never removed or given
an incompatible signature in a single step. It first spends at least one
minor release as a deprecated alias -- ``kornia.core._compat.deprecated``, or a shim
with the old signature where the old function scripted with TorchScript -- which
keeps the old call working while emitting a :class:`DeprecationWarning`
that names the replacement and the version that introduced the
deprecation.
2. **No silent semantic changes.** Changing a default that alters numerical
output (interpolation flags, ``align_corners``, padding modes, coordinate
conventions) counts as a breaking change and gets the same
deprecation-window treatment. The historical ``align_corners``
default flip, which changed results without erroring, is the exact
pattern this rule forbids.
3. **Release notes carry the ledger.** Every deprecation, removal, and
behavior change in the stable core is listed in the release notes of the
release that introduces it.
4. **Imports stay clean.** Importing kornia emits no warnings of its own β
none raised or triggered by kornia's import path, once PyTorch itself is
loaded. This is enforced by CI-gated tests (``tests/test_import.py``), so
downstream ``-W error`` users are safe.
5. **Conventions are stable.** The documented
:doc:`conventions </get-started/conventions>` (tensor layout, coordinate
order, angle units, homography conventions) are part of the API surface
and covered by the same rules.
What the stable core promises for ONNX export and ``torch.compile``, and where
CI checks it, is stated on the :ref:`support page <export-support-promise>`.
Versioning caveat
-----------------
Kornia is pre-1.0 and follows semver's 0.x semantics: minor releases (0.8 β
0.9) are where deprecation windows close and breaking changes land; patch
releases (0.9.0 β 0.9.1) are fixes only. The promises above are what makes
0.x livable: you get at least one minor release of warnings before anything
breaks.
Escape hatch
------------
A change that fixes a correctness bug (wrong math, wrong convention versus
the documented one) or a security issue may ship without a deprecation
window. When that happens the release notes say so explicitly.
Recording a completed deprecation
---------------------------------
Once the deprecation window has passed, remove the API and describe the removal
in a ``changelog.d/<PR>.breaking.md`` fragment. Update any existing entries in ``tests/api_surface.json``
in the same pull request; keep the module key, using an empty list if necessary.
The import-surface check verifies that recorded names leave the export surface
in that change. An inventory edit acknowledges an ``__all__`` removal only for
the exact same module and name; it does not authorize submodule removals.
Each module that declares ``__all__`` under a recorded package root has its own row.
To delete such a module, keep its key with an empty list: an empty row for a module
that no longer exists records the deletion, and stays in the inventory.
For an ``__all__`` name of a module that has no row of its own, such as a module
outside the recorded package roots, record the exact module and removed name in
``tests/api_surface_removals.json``. For example::
{
"kornia.feature.dedode": ["DeDoDe"]
}
Only module/name pairs newly added relative to the pull request's merge base
can acknowledge removals, and each must match an actual ``__all__`` removal in
the same change. Existing entries cannot authorize a later removal. When reintroducing an API,
remove its obsolete acknowledgement so a future removal requires a fresh entry.
This file does not replace updates to the inventory or the deprecation and release-note
requirements above.