DeepLabCut · deruyter92 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/deeplabcut/__init__.py b/deeplabcut/__init__.py
@@ -26,12 +26,19 @@
 if DEBUG:
     logger.debug("Loading DLC %s", VERSION)
 
+# DeepLabCut deprecation warnings are shown only once per message instance.
+import warnings
+
+from deeplabcut.core.deprecation import DLCDeprecationWarning
+
+warnings.filterwarnings("once", category=DLCDeprecationWarning)
+
 # -----------------------------------------------------------------------------
 # Always-available public API
 # -----------------------------------------------------------------------------
 
-# Train / evaluate / predict functions (compat layer)
-from .compat import (
+# Train / evaluate / predict functions
+from .api.pose_estimation import (
     analyze_images,
     analyze_time_lapse_frames,
     analyze_videos,

diff --git a/deeplabcut/api/__init__.py b/deeplabcut/api/__init__.py
@@ -0,0 +1,44 @@
+#
+# DeepLabCut Toolbox (deeplabcut.org)
+# © A. & M.W. Mathis Labs
+# https://github.com/DeepLabCut/DeepLabCut
+#
+# Please see AUTHORS for contributors.
+# https://github.com/DeepLabCut/DeepLabCut/blob/master/AUTHORS
+#
+# Licensed under GNU Lesser General Public License v3.0
+#
+"""
+Public API for DeepLabCut.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "analyze_images",
+    "analyze_time_lapse_frames",
+    "analyze_videos",
+    "convert_detections2tracklets",
+    "create_tracking_dataset",
+    "evaluate_network",
+    "export_model",
+    "extract_maps",
+    "extract_save_all_maps",
+    "return_evaluate_network_data",
+    "return_train_network_path",
+    "train_network",
+    "visualize_locrefs",
+    "visualize_paf",
+    "visualize_scoremaps",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name not in __all__:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from deeplabcut.api import pose_estimation
+
+    return getattr(pose_estimation, name)
diff --git a/deeplabcut/api/_tf_routing.py b/deeplabcut/api/_tf_routing.py
@@ -0,0 +1,180 @@
+#
+# DeepLabCut Toolbox (deeplabcut.org)
+# © A. & M.W. Mathis Labs
+# https://github.com/DeepLabCut/DeepLabCut
+#
+# Please see AUTHORS for contributors.
+# https://github.com/DeepLabCut/DeepLabCut/blob/master/AUTHORS
+#
+# Licensed under GNU Lesser General Public License v3.0
+#
+"""
+Routing for legacy TensorFlow API while still supported. Remove this module when TF support is dropped.
+"""
+
+import warnings
+from collections.abc import Callable
+from functools import lru_cache
+from importlib import import_module
+
+from deeplabcut.core.deprecation import DLCDeprecationWarning
+from deeplabcut.core.engine import Engine
+from deeplabcut.utils.auxiliaryfunctions import read_config
+
+_TF_MODULE = "deeplabcut.tensorflow_compat"
+
+
+@lru_cache
+def _get_tensorflow_impl(name: str):
+    return getattr(import_module(_TF_MODULE), name)
+
+
+def warn_deprecated_tensorflow():
+    warnings.warn(
+        "\n"
+        "━" * 60 + "\n"
+        "⚠️  DeepLabCut — TensorFlow support is deprecated\n"
+        "━" * 60 + "\n"
+        "TensorFlow support will be removed in a future release.\n"
+        "Your project config and annotated data are fully compatible with PyTorch.\n"
+        "Please run create_training_dataset with any PyTorch model architecture to switch to PyTorch.\n"
+        "See our docs for more information: https://deeplabcut.github.io/DeepLabCut/docs/pytorch/architectures.html\n"
+        "━" * 60,
+        DLCDeprecationWarning,
+        stacklevel=3,
+    )
+
+
+def with_tensorflow_fallback(
+    _fn: Callable | None = None,
+    *,
+    tensorflow_name: str | None = None,
+    renamed_params: dict[str, str] | None = None,
+    dropped_params: list[str] | None = None,
+    normalize_gputouse: bool = False,
+) -> Callable:
+    """Decorator for wrapping canonical PyTorch API functions, routing to a fallback TF function if required.
+    It automatically resolves the engine and converts legacy TensorFlow kwargs to canonical PyTorch kwargs, if needed.
+    Can be used with or without parentheses.
+
+    Args:
+        tensorflow_name (str | None): The name of the fallback TensorFlow function in ``_TF_MODULE``. If not specified,
+            uses the name of the canonical PyTorch function.
+        renamed_params (dict[str, str] | None): Optional mapping from old TF parameter names to the new canonical
+            PyTorch names. A warning will be emitted and the value is passed under the new canonical name. If both the
+            old and new names are specified, raises a TypeError.
+        dropped_params (list[str] | None): Optional list of dropped TensorFlow parameter names. A warning will be
+            emitted and the value is ignored.
+        normalize_gputouse (bool): resolve the old TF ``gputouse`` parameter to the new canonical PyTorch ``device``
+            parameter. Raises a TypeError if both are specified.
+
+    Note:
+        The engine is resolved from the shuffle metadata if not specified explicitly. If neither ``shuffles``,
+        ``shuffle`` or ``engine`` is passed, it assumes shuffle=1.
+    """
+
+    def decorator(fn):
+        tf_name = tensorflow_name or fn.__name__
+
+        def wrapper(*args, **kwargs):
+            engine = _resolve_engine(*args, **kwargs)
+            kwargs.pop("engine", None)
+            if engine == Engine.TF:
+                warn_deprecated_tensorflow()
+                return _get_tensorflow_impl(tf_name)(*args, **kwargs)
+            kwargs = _resolve_legacy_kwargs(
+                kwargs,
+                renamed_params=renamed_params or {},
+                dropped_params=dropped_params or [],
+                normalize_gputouse=normalize_gputouse,
+            )
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    if _fn is not None:
+        return decorator(_fn)
+    return decorator
+
+
+def _shuffles_from_kwargs(kwargs: dict) -> list | tuple:
+    """Return shuffle indices from kwargs, accepting legacy ``Shuffles``."""
+    if "shuffles" in kwargs and "Shuffles" in kwargs:
+        raise TypeError("Cannot specify both 'Shuffles' (deprecated) and 'shuffles'. Use 'shuffles' only.")
+    if "shuffles" in kwargs:
+        return kwargs["shuffles"]
+    if "Shuffles" in kwargs:
+        return kwargs["Shuffles"]
+    return [kwargs.get("shuffle", 1)]
+
+
+def _resolve_engine(*args, **kwargs) -> Engine:
+    """Resolve engine from explicit engine parameter or shuffle metadata."""
+    engine = kwargs.get("engine")
+    if engine is not None:
+        return engine
+
+    shuffles = _shuffles_from_kwargs(kwargs)
+    config = kwargs["config"] if "config" in kwargs else args[0]
+    cfg = read_config(config)
+    from deeplabcut.generate_training_dataset.metadata import get_shuffle_engine
+
+    engines = {
+        get_shuffle_engine(
+            cfg,
+            trainingsetindex=kwargs.get("trainingsetindex", 0),
+            shuffle=s,
+            modelprefix=kwargs.get("modelprefix", ""),
+        )
+        for s in shuffles
+    }
+    if len(engines) > 1:
+        raise ValueError(f"All shuffles must have the same engine (found different engines for shuffles: {shuffles}).")
+    return engines.pop()
+
+
+def _normalize_gputouse(gputouse: str | int) -> str:
+    if isinstance(gputouse, int):
+        return f"cuda:{gputouse}"
+    if gputouse.startswith("cuda:"):
+        return gputouse
+    if gputouse.startswith("gpu:"):
+        return gputouse.replace("gpu:", "cuda:")
+    return gputouse
+
+
+def _resolve_legacy_kwargs(
+    kwargs: dict,
+    renamed_params: dict[str, str],
+    dropped_params: list[str],
+    normalize_gputouse: bool = False,
+) -> dict:
+    """Resolve legacy TensorFlow kwargs to canonical (PyTorch) kwargs."""
+
+    if normalize_gputouse and (gpu := kwargs.get("gputouse")):
+        # Normalize parameter "gputouse" to torch device string and rename
+        kwargs["gputouse"] = _normalize_gputouse(gpu)
+        renamed_params["gputouse"] = "device"
+
+    # Rename deprecated parameters
+    for old, new in renamed_params.items():
+        if old in kwargs:
+            if new in kwargs:
+                raise TypeError(f"Cannot specify both '{old}' (deprecated) and '{new}'. Use '{new}' only.")
+            kwargs[new] = kwargs.pop(old)
+            warnings.warn(
+                f"'{old}' is deprecated; use {new}='{kwargs[new]}' instead.",
+                DLCDeprecationWarning,
+                stacklevel=3,
+            )
+
+    # Drop unused parameters
+    for key in dropped_params:
+        if key in kwargs:
+            kwargs.pop(key)
+            warnings.warn(
+                f"'{key}' is a TensorFlow-only parameter and has no effect for PyTorch projects.",
+                DLCDeprecationWarning,
+                stacklevel=3,
+            )
+    return kwargs