Neural network backend for training and inference for animal pose estimation.
-
Install miniforge
We recommend using miniforge for an isolated Python environment with fast dependency resolution. -
Create and activate the development environment using Python 3.11
mamba create -n sleap-nn-dev python=3.11 mamba activate sleap-nn-dev
-
Install
uvand development dependencies
uvis a fast and modern package manager forpyproject.toml-based projects.pip install uv uv pip install -e ".[dev]" -
Install PyTorch based on your platform
By default, the CPU-only version oftorchis installed from PyPI.
For GPU support, install the correct wheel after installing other dependencies:-
Windows/Linux with NVIDIA GPU (CUDA 11.8):
pip install --upgrade --force-reinstall torch torchvision --index-url https://download.pytorch.org/whl/cu118
-
macOS with Apple Silicon (M1, M2, M3, M4): You don’t need to do anything. The default wheels now include Metal backend support for Apple GPUs.
-
CPU-only (no GPU or unsupported GPU):
You don’t need to do anything. The CPU version will already be installed viapyproject.toml.
You can find the correct wheel for your system at:
👉 https://pytorch.org/get-started/locally -
-
Run tests
pytest tests
-
(Optional) Lint and format code
black --check sleap_nn tests ruff check sleap_nn/
We intentionally do not include GPU-specific torch or torchvision builds in pyproject.toml. Instead, we recommend installing them manually based on your platform.
- Portability: No CUDA version or hardware is assumed. This avoids broken installs on unsupported platforms.
- Flexibility: You can use the appropriate PyTorch build for your system.
- Reliability: All other dependencies are managed cleanly with
uv.
💡 This makes
sleap-nncompatible with both GPU-accelerated and CPU-only environments.
📦 Why not use `pyproject.toml` for GPU builds?
- GPU wheels are not on PyPI — they live at https://download.pytorch.org/whl/
- These builds vary by platform, CUDA version, and GPU architecture.
uvdoes not currently support CLI-based extra index URLs like pip’s--index-url.- Hardcoding GPU wheels into
pyproject.tomlwould break cross-platform support.
This repository uses GitHub Actions for continuous integration and publishing:
Runs on every pull request and performs the following:
- Sets up a Conda environment using Miniforge3 with Python 3.11.
- Installs
uvand uses it to install the package in editable mode with dev dependencies. - Runs code quality checks using
blackandruff. - Executes the test suite using
pytestwith coverage reporting. - Uploads coverage results to Codecov.
Runs on all major operating systems (ubuntu-latest, windows-latest, macos-14).
Triggered on GitHub Releases:
- For pre-releases, the package is published to Test PyPI for testing.
- For final releases, the package is published to the official PyPI registry using trusted publishing.
The uv tool is used for both building and publishing. You can create a pre-release by tagging your release with a version suffix like 1.0.0rc1 or 1.0.0b1.
To test the pre-release in your development workflow:
uv pip install --index-url https://test.pypi.org/simple/ sleap-nnTrusted publishing is handled automatically using GitHub OIDC, and no credentials are stored.