sleap-nn

Neural network backend for training and inference for animal pose estimation.

This is the deep learning engine that powers SLEAP (Social LEAP Estimates Animal Poses), providing neural network architectures for multi-instance animal pose estimation and tracking. Built on PyTorch, SLEAP-NN offers an end-to-end training workflow, supporting multiple model types (Single Instance, Top-Down, Bottom-Up, Multi-Class), and seamless integration with SLEAP's GUI and command-line tools.

Need a quick start? Refer to our Quick Start guide in the docs.

Documentation

Documentation - Comprehensive guides and API reference

For development setup

1. Clone the sleap-nn repo

git clone https://github.com/talmolab/sleap-nn.git
cd sleap-nn

2. Install uv Install uv first - a fast Python package manager:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Install sleap-nn dependencies based on your platform\

Python 3.14 is not yet supported

sleap-nn currently supports Python 3.11, 3.12, and 3.13. Python 3.14 is not yet tested or supported. By default, uv will use your system-installed Python. If you have Python 3.14 installed, you must specify the Python version (≤3.13) in the install command.

For example:

uv sync --python 3.13 ...

Replace ... with the rest of your install command as needed.

• Install everything with a single command. uv sync creates a .venv (virtual environment) inside your current working directory. This environment is only active within that directory and can't be directly accessed from outside. To use installed packages, run commands with uv run (e.g., uv run sleap-nn train ... or uv run pytest ...).

  uv sync
  

  This installs the CUDA 13.0 GPU build on Windows/Linux (x86-64) and the Apple-MPS build on macOS automatically, and uv run keeps it. A GPU is not required — the CUDA wheel also runs on CPU.

  _{Want the smaller CPU-only wheel (CPU-only machines/CI, Linux aarch64) or a specific CUDA version? Add --no-group gpu, e.g. uv sync --no-group gpu --extra cpu or uv sync --no-group gpu --extra torch-cuda128.}

4. Run tests

   uv run pytest tests
   

5. (Optional) Lint and format code

   uv run black --check sleap_nn tests
   uv run ruff check sleap_nn/
   

Upgrading All Dependencies To ensure you have the latest versions of all dependencies, use the --upgrade flag with uv sync:

uv sync --upgrade

This will upgrade all installed packages in your environment to the latest available versions compatible with your pyproject.toml.