DeepLabCut · MMathisLab · Mar 30, 2026 · Feb 23, 2026 · Feb 23, 2026 · Feb 23, 2026
diff --git a/.github/versioning/tf-ci-constraints.txt b/.github/versioning/tf-ci-constraints.txt
@@ -1 +1 @@
-protobuf<7
+protobuf<7
diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml
@@ -0,0 +1,116 @@
+name: pre-commit (PR only on changed files)
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect_changes:
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.changed_files.outputs.changed }}
+      changed_python: ${{ steps.changed_python.outputs.changed_python }}
+
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files
+        id: changed_files
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+
+          {
+            echo "changed<<EOF"
+            echo "$CHANGED_FILES"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Detect changed Python files
+        id: changed_python
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          CHANGED_PYTHON=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(py|pyi|ipynb)$' || true)
+
+          {
+            echo "changed_python<<EOF"
+            echo "$CHANGED_PYTHON"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Show changed files
+        run: |
+          echo "Changed files:"
+          echo "${{ steps.changed_files.outputs.changed }}"
+
+          echo
+          echo "Changed Python files:"
+          echo "${{ steps.changed_python.outputs.changed_python }}"
+
+  precommit:
+    needs: detect_changes
+    runs-on: ubuntu-latest
+    if: ${{ needs.detect_changes.outputs.changed != '' }}
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install tooling
+        run: pip install pre-commit ruff
+
+      - name: Run pre-commit (CI check-only stage) on changed files
+        id: precommit_run
+        continue-on-error: true
+        env:
+          CHANGED_FILES: ${{ needs.detect_changes.outputs.changed }}
+        run: |
+          mapfile -t files <<< "$CHANGED_FILES"
+          pre-commit run --hook-stage manual --files "${files[@]}" --show-diff-on-failure
+
+      - name: Generate Ruff Markdown report
+        id: ruff_report
+        if: ${{ always() && needs.detect_changes.outputs.changed_python != '' }}
+        env:
+          CHANGED_PYTHON: ${{ needs.detect_changes.outputs.changed_python }}
+        run: |
+          mkdir -p tmp
+          mapfile -t pyfiles <<< "$CHANGED_PYTHON"
+          python tools/ruff_report.py "${pyfiles[@]}" --output tmp/ruff-report.md
+
+      - name: Add short Ruff report to GitHub Actions summary
+        if: ${{ always() && steps.precommit_run.outcome == 'failure' && needs.detect_changes.outputs.changed_python != '' }}
+        run: |
+          {
+            echo "# Lint summary"
+            echo
+            echo "## Ruff report (top section)"
+            echo
+            sed -n '1,80p' tmp/ruff-report.md
+            echo
+            echo "_Full report uploaded as workflow artifact: `ruff-report`_"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload Ruff report artifact
+        if: ${{ always() && needs.detect_changes.outputs.changed_python != '' }}
+        uses: actions/upload-artifact@v6
+        with:
+          name: ruff-report
+          path: tmp/ruff-report.md
+
+      - name: Fail job if pre-commit failed
+        if: ${{ steps.precommit_run.outcome == 'failure' }}
+        run: |
+          echo "pre-commit reported failures"
+          exit 1
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -67,7 +67,7 @@ jobs:
       - name: Set up Python
         uses: conda-incubator/setup-miniconda@v3
         with:
-          channels: conda-forge,defaults
+          channels: conda-forge
           channel-priority: strict
           python-version: ${{ matrix.python-version }}
 

diff --git a/.gitignore b/.gitignore
@@ -136,6 +136,12 @@ ENV/
 # mypy
 .mypy_cache/
 
+# Tools output
+tmp/*
+
+# Test data
+tests/data/*
+
 # Automated docs checks
 **/tmp/docs_nb_checks/
 

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,31 +1,88 @@
+default_stages: [pre-commit]
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v6.0.0
     hooks:
+      # These are safe to run in both local & CI (they don't require "fix vs check" split)
       - id: check-added-large-files
+        stages: [pre-commit, manual]
       - id: check-yaml
+        stages: [pre-commit, manual]
       - id: check-toml
-      - id: end-of-file-fixer
+        stages: [pre-commit, manual]
+      - id: check-merge-conflict
+        stages: [pre-commit, manual]
       - id: name-tests-test
         args: [--pytest-test-first]
+        stages: [pre-commit, manual]
+
+      # These modify files. Run locally only (pre-commit stage).
+      - id: end-of-file-fixer
+        stages: [pre-commit]
       - id: trailing-whitespace
+        stages: [pre-commit]
+
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.15.2
+    rev: v2.19.0
     hooks:
       - id: pyproject-fmt
+        stages: [pre-commit]    # modifies -> local only
+
   - repo: https://github.com/abravalheri/validate-pyproject
     rev: v0.25
     hooks:
       - id: validate-pyproject
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-  - repo: https://github.com/psf/black
-    rev: 22.3.0
+        stages: [pre-commit, manual]
+
+  # NOTE: @C-Achard 2026-03-18 disabled for now
+  # It had its use in introducing and enforcing linting, especially for docstrings
+  # but now ruff should be our de-facto linter.
+  # Only re-enable if we end up requiring large-scale docstring reformatting
+  # or we need some features from this in the future
+  # - repo: https://github.com/PyCQA/docformatter
+  #   rev: v1.7.7
+  #   hooks:
+  #     - id: docformatter
+  #       name: docformatter (fix)
+  #       args: [--wrap-descriptions=88, --wrap-summaries=88, --in-place, --black]
+  #       stages: [pre-commit]
+
+  #     - id: docformatter
+  #       name: docformatter (ci)
+  #       args: [--wrap-descriptions=88, --wrap-summaries=88, --check, --black]
+  #       stages: [manual]
+
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
     hooks:
-      - id: black
-        language_version: python3
+      # --------------------------
+      # LOCAL AUTOFIX (developers)
+      # --------------------------
+      - id: ruff-check
+        name: ruff-check (fix)
+        args: [--fix, --unsafe-fixes]
+        stages: [pre-commit]
+
+      - id: ruff-format
+        name: ruff-format (write)
+        stages: [pre-commit]
+
+      # --------------------------
+      # CI CHECK-ONLY (no writes)
+      # --------------------------
+      - id: ruff-check
+        name: ruff-check (ci)
+        args: [--output-format=github]
+        stages: [manual]
+
+      - id: ruff-format
+        name: ruff-format (ci)
+        args: [--check, --diff]
+        stages: [manual]
+
+  # check only, no modifications
   - repo: local
     hooks:
       - id: dlc-docs-notebooks-check
@@ -43,3 +100,4 @@ repos:
           - "pydantic>=2,<3"
           - "pyyaml"
           - "nbformat>=5"
+        stages: [pre-commit, manual]
diff --git a/LICENSE b/LICENSE
@@ -163,4 +163,3 @@ whether future versions of the GNU Lesser General Public License shall
 apply, that proxy's public statement of acceptance of any version is
 permanent authorization for you to choose that version for the
 Library.
-
diff --git a/NOTICE.yml b/NOTICE.yml
@@ -109,7 +109,7 @@
     - deeplabcut/pose_tracking_pytorch/solver/scheduler_factory.py
     - deeplabcut/pose_tracking_pytorch/model/backones/vit_pytorch.py
 
-# PyTorch license 
+# PyTorch license
 
 - header: |
     See https://github.com/pytorch/pytorch/blob/main/LICENSE
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <div align="center">
-  
+
 
 <p align="center">
 <img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1628250004229-KVYD7JJVHYEFDJ32L9VJ/DLClogo2021.jpg?format=1000w" width="95%">
@@ -8,7 +8,7 @@
 <p align="center">
 
 <img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1619609897110-TKSTWKEM6HTGXID9D489/ke17ZwdGBToddI8pDm48kAvjv6tW_eojYQmNU0ncbllZw-zPPgdn4jUwVcJE1ZvWEtT5uBSRWt4vQZAgTJucoTqqXjS3CfNDSuuf31e0tVHBSTXHtjUKlhRtWJ1Vo6l1B2bxJtByvWSjL6Vz3amc5yb8BodarTVrzIWCp72ioWw/triMouseDLC.gif?format=180w" height="150">
-  
+
 
 <img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/daed7f16-527f-4150-8bdd-cbb20e267451/cheetah-ezgif.com-video-to-gif-converter.gif?format=180w" height="150">
 
@@ -18,7 +18,7 @@
 
 
 
-  
+
 
 
 
@@ -27,13 +27,13 @@
 [🌎 Home Page](https://www.deeplabcut.org) |
 [🐿🐴🐁🐘🐆 Model Zoo](http://www.mackenziemathislab.org/deeplabcut/) |
 [🚨 News](https://deeplabcut.github.io/DeepLabCut/README.html#news-and-in-the-news) |
-[🪲 Reporting Issues](https://github.com/DeepLabCut/DeepLabCut/issues) 
+[🪲 Reporting Issues](https://github.com/DeepLabCut/DeepLabCut/issues)
 
 
-[🫶 Getting Assistance](https://deeplabcut.github.io/DeepLabCut/README.html#be-part-of-the-dlc-community) | 
-[∞ DeepLabCut Online Course](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/master/DLCcourse.md) | 
-[📝 Publications](https://deeplabcut.github.io/DeepLabCut/README.html#references) | 
-[👩🏾‍💻👨‍💻 DeepLabCut AI Residency](https://www.deeplabcutairesidency.org/) 
+[🫶 Getting Assistance](https://deeplabcut.github.io/DeepLabCut/README.html#be-part-of-the-dlc-community) |
+[∞ DeepLabCut Online Course](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/master/DLCcourse.md) |
+[📝 Publications](https://deeplabcut.github.io/DeepLabCut/README.html#references) |
+[👩🏾‍💻👨‍💻 DeepLabCut AI Residency](https://www.deeplabcutairesidency.org/)
 
 
 ![Version](https://img.shields.io/badge/python_version-3.10-purple)
@@ -55,15 +55,15 @@
 
 # Welcome! 👋
 
-**DeepLabCut™️** is a toolbox for state-of-the-art markerless pose estimation of animals performing various behaviors. As long as you can see (label) what you want to track, you can use this toolbox, as it is animal and object agnostic. [Read a short development and application summary below](https://github.com/DeepLabCut/DeepLabCut#why-use-deeplabcut). 
+**DeepLabCut™️** is a toolbox for state-of-the-art markerless pose estimation of animals performing various behaviors. As long as you can see (label) what you want to track, you can use this toolbox, as it is animal and object agnostic. [Read a short development and application summary below](https://github.com/DeepLabCut/DeepLabCut#why-use-deeplabcut).
 
 # [Installation: how to install DeepLabCut](https://deeplabcut.github.io/DeepLabCut/docs/installation.html)
 
 Please click the link above for all the information you need to get started! Please note that currently we support only Python 3.10+ (see conda files for guidance).
 
 ## Quick start
 
-Developers Stable Release: very quick start (Python 3.10+ required) to install 
+Developers Stable Release: very quick start (Python 3.10+ required) to install
 DeepLabCut with the PyTorch engine
 
 - [1] [Install PyTorch](https://pytorch.org/get-started/locally/) (**install and then select the desired
@@ -77,15 +77,15 @@ conda install pytorch cudatoolkit=11.3 -c pytorch
 ```bash
 pip install --pre  "deeplabcut[gui]"
 ```
-or `pip install  --pre "deeplabcut"` (headless 
+or `pip install  --pre "deeplabcut"` (headless
 version with PyTorch)!
 
 To use the TensorFlow (TF) engine (requires Python 3.10; TF up to v2.10 supported on Windows,
-up to v2.12 on other platforms): you'll need to run `pip install "deeplabcut[gui,tf]"` 
+up to v2.12 on other platforms): you'll need to run `pip install "deeplabcut[gui,tf]"`
 (which includes all functions plus GUIs) or `pip install "deeplabcut[tf]"` (headless
 version with PyTorch and TensorFlow). We aim to depreciate the TF part in 2027.
 
-We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker). 
+We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker).
 
 # [Documentation: The DeepLabCut Process](https://deeplabcut.github.io/DeepLabCut/README.html)
 
@@ -105,11 +105,11 @@ See [more demos here](https://github.com/DeepLabCut/DeepLabCut/blob/main/example
 
 # Why use DeepLabCut?
 
-DeepLabCut continues to be actively maintained and we strive to provide a user-friendly `GUI` and `API` for computer vision researchers and life scientists alike. This means we integrate state-of-the-art models and frameworks, while providing our "best-guess" defaults for life scientists. We highly encourage you to read our papers to get a better understanding of what to use and how to modify the models for your setting. 
+DeepLabCut continues to be actively maintained and we strive to provide a user-friendly `GUI` and `API` for computer vision researchers and life scientists alike. This means we integrate state-of-the-art models and frameworks, while providing our "best-guess" defaults for life scientists. We highly encourage you to read our papers to get a better understanding of what to use and how to modify the models for your setting.
 
 ## Performance 🔥
 
-In general, we provide all the tooling for you to train and use custom models with various high-performance backbones. 
+In general, we provide all the tooling for you to train and use custom models with various high-performance backbones.
 We also provide two foundation pretrained animal models: `SuperAnimal-Quadruped`, `SuperAnimal-TopViewMouse`. To gauge their *out-of-distribution* performance, we provide the following tables.
 
 These models are trained on the [SuperAnimal-Quadruped with AP-10K held out for out-of-domain testing]([https://cocodataset.org/](https://www.nature.com/articles/s41467-024-48792-2)) and the [SuperAnimal-TopViewMouse with DLC-openfield held out for out-of-distribution testing](https://www.nature.com/articles/s41467-024-48792-2). We provide models that include AP-10K in the API (and GUI).
@@ -139,7 +139,7 @@ We currently provide state-of-the-art performance for animal pose estimation and
 <p align="center">
 <img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5c3e47258a922d548c483247/1547585339819/ErrorvsTrainingsetSize.png?format=750w" height="160">
 <img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5c3e469d8a922d548c4828fa/1547585194560/compressionrobustness.png?format=750w" height="160">
-<img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5c3fbed74fa51acecd63deeb/1547681534736/MouseLocomotion_warren.gif?format=500w" height="160">  
+<img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5c3fbed74fa51acecd63deeb/1547681534736/MouseLocomotion_warren.gif?format=500w" height="160">
 <img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5c3fc1c6758d46950ce7eec7/1547682383595/cheetah.png?format=750w" height="160">
 </p>
 
@@ -169,7 +169,7 @@ DeepLabCut is an open-source tool and has benefited from suggestions and edits b
 |------------------------------------------------------------|-----------------------------------------------------------------------------|---------------------------|----------------------------------------|
 | GitHub DeepLabCut/[Issues](https://github.com/DeepLabCut/DeepLabCut/issues)                                  | To report bugs and code issues🐛   (we encourage you to search issues first) | 2-5 days                  | DLC Core Dev Team                               |
 | GitHub DeepLabCut/[Contributing](https://github.com/DeepLabCut/DeepLabCut/blob/master/CONTRIBUTING.md)                          | To contribute your expertise and experience🙏💯                               | 2-5 days                | DLC Core Dev Team                               |
-| 🚧 GitHub DeepLabCut/[Roadmap](https://github.com/DeepLabCut/DeepLabCut/blob/master/docs/roadmap.md)                             | To learn more about our journey✈️                                            | N/A                       | N/A                                    
+| 🚧 GitHub DeepLabCut/[Roadmap](https://github.com/DeepLabCut/DeepLabCut/blob/master/docs/roadmap.md)                             | To learn more about our journey✈️                                            | N/A                       | N/A
 | [![Image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&amp;url=https%3A%2F%2Fforum.image.sc%2Ftag%2Fdeeplabcut.json&amp;query=%24.topic_list.tags.0.topic_count&amp;colorB=brightgreen&amp;&amp;suffix=%20topics&amp;logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tag/deeplabcut) <br /> 🐭Tag: DeepLabCut | To ask help and support questions 👋                                          | Promptly🔥                 | The DLC Community |
 |[![Gitter](https://badges.gitter.im/DeepLabCut/community.svg)](https://gitter.im/DeepLabCut/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)                               | To discuss with other users,  share ideas and collaborate💡                  | 2-5 days                    | The DLC Community                      |
 | [BluSky🦋](https://bsky.app/profile/deeplabcut.bsky.social)                                                  | To keep up with our latest news and updates 📢                               | 2-5 days                     | DLC Team                               |
@@ -217,7 +217,7 @@ VERSION 1.0: The initial, Nature Neuroscience version of [DeepLabCut](https://ww
 
 - June 2024: Our second DLC paper ['Using DeepLabCut for 3D markerless pose estimation across species and behaviors'](https://www.nature.com/articles/s41596-019-0176-0) in Nature Protocols has surpassed 1,000 Google Scholar citations!
 - May 2024: DeepLabCut was featured in Nature: ['DeepLabCut: the motion-tracking tool that went viral'](https://www.nature.com/articles/d41586-024-01474-x)
-- January 2024: Our original paper ['DeepLabCut: markerless pose estimation of user-defined body parts with deep learning'](https://www.nature.com/articles/s41593-018-0209-y) in Nature Neuroscience has surpassed 3,000 Google Scholar citations! 
+- January 2024: Our original paper ['DeepLabCut: markerless pose estimation of user-defined body parts with deep learning'](https://www.nature.com/articles/s41593-018-0209-y) in Nature Neuroscience has surpassed 3,000 Google Scholar citations!
 - December 2023: DeepLabCut hit 600,000 downloads!
 - October 2023: DeepLabCut celebrates a milestone with 4,000 🌟 in Github!
 - July 2023: The user forum is very active with more than 1k questions and answers: [![Image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&amp;url=https%3A%2F%2Fforum.image.sc%2Ftag%2Fdeeplabcut.json&amp;query=%24.topic_list.tags.0.topic_count&amp;colorB=brightgreen&amp;&amp;suffix=%20topics&amp;logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tag/deeplabcut)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -163,4 +163,3 @@ whether future versions of the GNU Lesser General Public License shall
		apply, that proxy's public statement of acceptance of any version is
		permanent authorization for you to choose that version for the
		Library.