Installation¶

Before You Start¶

SLEAP-NN uses uv for installation and environment management. If you're coming from conda/pip, this section explains why.

Why uv?

GPU dependencies are complex. PyTorch requires matching CUDA versions, platform-specific wheels, and careful index configuration. Traditional pip/conda installs often result in CPU-only PyTorch or version conflicts.

uv solves this with the --torch-backend flag:

auto – Detects your GPU and installs the right PyTorch
cu130 / cu128 – Explicit CUDA versions
cpu – CPU-only (smaller install)

One command, correct GPU support. No manual index URLs or environment debugging.

uv version requirement

The --torch-backend flag for uv tool install requires uv 0.9.20+. Run uv self update if you encounter errors.

Can I still use pip/conda?

Yes. See the pip installation section below. You'll need to manually configure PyTorch index URLs.

Install SLEAP-NN¶

Linux / WindowsmacOSCPU Only

Step 1: Install uv

Linux / macOS / WSLWindows (PowerShell)

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

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

Step 2: Install sleap-nn

Python 3.14 not supported

If you don't have Python installed, uv will automatically download the latest version (Python 3.14), which is not yet supported. Add --python 3.13 to specify a compatible version:

uv tool install --python 3.13 sleap-nn --torch-backend auto

uv tool install sleap-nn --torch-backend auto

This auto-detects your GPU and installs the correct PyTorch build. You can also specify a backend explicitly:

# Explicit CUDA 13.0
uv tool install sleap-nn --torch-backend cu130

# CPU-only (smaller install)
uv tool install sleap-nn --torch-backend cpu

Step 3: Verify

sleap-nn system

Step 1: Install uv

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

Step 2: Install sleap-nn

Python 3.14 not supported

If you don't have Python installed, uv will automatically download the latest version (Python 3.14), which is not yet supported. Add --python 3.13 to specify a compatible version:

uv tool install --python 3.13 sleap-nn

uv tool install sleap-nn

Apple Silicon

PyTorch uses Metal Performance Shaders (MPS) for GPU acceleration on M1/M2/M3 Macs. No additional configuration needed.

Step 3: Verify

sleap-nn system

Step 1: Install uv

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

Step 2: Install sleap-nn

Python 3.14 not supported

If you don't have Python installed, uv will automatically download the latest version (Python 3.14), which is not yet supported. Add --python 3.13 to specify a compatible version:

uv tool install --python 3.13 sleap-nn --torch-backend cpu

uv tool install sleap-nn --torch-backend cpu

Step 3: Verify

sleap-nn system

Updating¶

Update to latestUpdate to specific versionReinstall (fix issues)DowngradeUninstall

uv tool upgrade sleap-nn

Note

This preserves the torch backend from your original installation. If you need to change the torch backend, use the reinstall option.

uv tool install "sleap-nn==0.1.0" --torch-backend auto --force

uv tool install sleap-nn --torch-backend auto --reinstall

When to use --reinstall

Use this when you've updated CUDA drivers, changed GPUs, or have import errors.

uv tool install "sleap-nn==0.0.5" --torch-backend auto --force

uv tool uninstall sleap-nn

Pre-release Versions¶

Install alpha/beta releases to test new features:

uv tool install sleap-nn --torch-backend auto --prerelease=allow

Install a specific pre-release:

uv tool install "sleap-nn==0.1.0a4" --torch-backend auto

Alternative Methods¶

uvx (No Install)¶

Run sleap-nn without permanent installation. Each command creates a temporary environment.

# Train
uvx --from sleap-nn --torch-backend auto sleap-nn train --config config.yaml

# Inference
uvx --from sleap-nn --torch-backend auto sleap-nn predict -i video.mp4 -m models/

Always latest

uvx uses the latest version each run. Great for testing or one-off tasks.

pip¶

Use pip when working within conda/mamba environments.

Create environment:

conda create -n sleap-nn python=3.13
conda activate sleap-nn

Install with GPU support:

Default (PyPI)CUDA 12.8CUDA 11.8CPU OnlymacOS

pip install sleap-nn

Note

PyTorch wheels on PyPI include CUDA support on Linux and Windows. This is the simplest option and works for most users.

pip install sleap-nn \
    --index-url https://pypi.org/simple \
    --extra-index-url https://download.pytorch.org/whl/cu128

pip install sleap-nn \
    --index-url https://pypi.org/simple \
    --extra-index-url https://download.pytorch.org/whl/cu118

pip install sleap-nn \
    --index-url https://pypi.org/simple \
    --extra-index-url https://download.pytorch.org/whl/cpu

pip install sleap-nn

Other CUDA versions

You can install any CUDA version supported by PyTorch by changing the index URL. Replace cu128 with your desired version (e.g., cu124, cu121, cu118). See PyTorch Get Started for available versions.

Verify:

sleap-nn system

From Source¶

For development and contributing.

Step 1: Clone repository

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

Step 2: Install uv (if needed)

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

Step 3: Install in development mode

uv sync

gpu is a default dependency group, so a plain uv sync installs the CUDA 13.0 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.

Escape hatch: CPU-only wheel or a specific CUDA version

Drop the default group with --no-group gpu and add an extra:

Command	Backend
`uv sync --no-group gpu --extra cpu`	smaller CPU-only wheel (also Linux aarch64)
`uv sync --no-group gpu --extra torch-cuda128`	CUDA 12.8
`uv sync --no-group gpu --extra torch-cuda118`	CUDA 11.8

The gpu / torch-cuda130 extras (uv sync --extra gpu) resolve to the same cu130 wheel as the default group, so they don't need --no-group gpu. On Windows the CUDA runtime (incl. cuDNN) ships inside the torch wheel; on Linux nvidia-cudnn-cu13 is a separate dependency.

Step 4: Run commands

uv run sleap-nn --help

uv run pytest tests/

See Contributing for development guidelines.

System Requirements¶

Requirement	Minimum	Recommended
Python	3.11	3.13
RAM	8 GB	16+ GB

Apple Silicon

M1/M2/M3 Macs are fully supported via Metal Performance Shaders (MPS).

Python 3.14

Not yet supported. Use --python 3.13 with uv commands.

Troubleshooting¶

Command not found after install

Restart your terminal or source your shell config:

source ~/.bashrc  # or ~/.zshrc on macOS

Verify the tool is installed:

uv tool list

CUDA not detected

Check NVIDIA drivers:
```
nvidia-smi
```
Check sleap-nn detects CUDA:
```
sleap-nn system
```

Reinstall with explicit CUDA version:

uv tool install sleap-nn --torch-backend cu128 --reinstall

Import errors or missing modules

Reinstall sleap-nn:

uv tool install sleap-nn --torch-backend auto --reinstall

Wrong Python version

Specify the Python version explicitly:

uv tool install --python 3.13 sleap-nn --torch-backend auto

uv version too old

The --torch-backend flag requires uv 0.9.20+.

# Check version
uv --version

# Update uv
uv self update

Next Steps¶

Quick Start

Train your first model in 5 minutes.

Get started
Your First Model

Complete walkthrough from data to predictions.

Tutorial