Installation

Prerequisites: Python 3.11+ (required for all installation methods)

Choose Your Installation Method

• Installation as a system-wide tool with uv: (Recommended) Use uv tool install to install sleap-nn globally as a CLI tool
• Installation with uvx: Use uvx for one-off commands (no installation needed)
• Installation with uv pip: Use uv pip to install from pypi in a uv virtual env.
• Installation with pip: Use pip to install from pypi in a conda env. (Recommended to use with a conda env)
• Installation from source: Use uv sync to install from source (for developmental purposes)

---

Installation as a system-wide tool with uv

uv tool install installs sleap-nn globally as a system-wide CLI tool, making sleap-nn commands available from anywhere in your terminal.

Install uv

Install uv - a fast Python package manager:

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

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

Platform-Specific Installation

Windows/Linux (CUDA)Windows/Linux (CPU)macOS

# CUDA 12.8
uv tool install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128

# CUDA 11.8
uv tool install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu118

uv tool install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu

uv tool install "sleap-nn[torch]"

Info

• For more information on which CUDA version to use for your system, see the PyTorch installation guide.
  The --extra-index-url in the install command should match the CUDA version you need (e.g., https://download.pytorch.org/whl/cuda118 for CUDA 11.8, https://download.pytorch.org/whl/cuda128 for CUDA 12.8, etc.).
• On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

Verify installation

# Test the installation
sleap-nn --help

---

Installation with uvx

uvx automatically installs sleap-nn and runs your command inside a temporary virtual environment (venv). This means each run is fully isolated and leaves no trace on your system—perfect for trying out sleap-nn without any permanent installation.

Install uv

Install uv - a fast Python package manager:

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

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

Platform-Specific Commands

Windows/Linux (CUDA)Windows/Linux (CPU)macOS

uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128 sleap-nn train --config-name myconfig --config-dir /path/to/config_dir/
uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128 sleap-nn track --data_path video.mp4 --model_paths models/

uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu sleap-nn train --config-name myconfig --config-dir /path/to/config_dir/
uvx --from "sleap-nn[torch]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu sleap-nn track --data_path video.mp4 --model_paths models/

uvx "sleap-nn[torch]" train --config-name myconfig --config-dir /path/to/config_dir/
uvx "sleap-nn[torch]" track --data_path video.mp4 --model_paths models/

Note

• For more information on which CUDA version to use for your system, see the PyTorch installation guide.
  The --extra-index-url in the install command should match the CUDA version you need (e.g., https://download.pytorch.org/whl/cuda118 for CUDA 11.8, https://download.pytorch.org/whl/cuda128 for CUDA 12.8, etc.).
• On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

How uvx Works

• Automatic Installation: Downloads and installs sleap-nn with dependencies
• Isolated Environment: Each command runs in a clean, temporary environment
• No Conflicts: Won't interfere with your existing Python packages
• Uses recent pkgs: Uses the latest version from PyPI

uvx Installation

Because uvx installs packages fresh on every run, it's ideal for quick tests or use in remote environments. For regular use, you could install with uv tool install or setting up a development environment with uv sync to avoid repeated downloads.

---

Installation with uv pip

This method creates a dedicated project environment using uv's modern Python project management. It initializes a new project with uv init, creates an isolated virtual environment with uv venv, and installs sleap-nn using uv pip. To use all installed packages, you must run commands with uv run (e.g., uv run sleap-nn train ... or uv run pytest ...).

Install and set-up uv

Step-1: Install uv - a fast Python package manager:

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

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

Step-2: Move to your project directory and initialize the virtual env.

uv init
uv venv

Platform-Specific Installation

Windows/Linux (CUDA)Windows/Linux (CPU)macOS

# CUDA 12.8
uv pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128

# CUDA 11.8
uv pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu118

uv pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cpu

uv pip install "sleap-nn[torch]"

Info

• For more information on which CUDA version to use for your system, see the PyTorch installation guide.
  The --extra-index-url in the install command should match the CUDA version you need (e.g., https://download.pytorch.org/whl/cuda118 for CUDA 11.8, https://download.pytorch.org/whl/cuda128 for CUDA 12.8, etc.).
• On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

Verify Installation

# Test the installation
uv run sleap-nn --help

sleap-nn not recognized after installation?

If running the verification step above gives an error like sleap-nn: command not found or 'sleap-nn' is not recognized as an internal or external command, try the following workarounds:

• Activate your virtual environment (the venv name should be the same as your current working dir name). If you used uv, activate it and then run:

  uv run --active sleap-nn --help
  

  This ensures the command runs in the correct environment.

• Another workaround (not recommended):
  Check if you have any empty pyproject.toml or uv.lock files in Users/<your-user-name>. If you find empty files with these names, delete them and try again. (Empty files here can sometimes interfere with uv's environment resolution.)

---

Installation with pip

We recommend creating a dedicated environment with conda or mamba/miniforge before installing sleap-nn with pip. This helps avoid dependency conflicts and keeps your Python setup clean. After installing Miniconda or Miniforge, create and activate an environment, then run the pip install commands below inside the activated environment.

To create a conda environment, run:

conda create -n sleap-nn-env python=3.12
conda activate sleap-nn-env

Platform-Specific Installation

Windows/Linux (CUDA)Windows/Linux (CPU)macOS

# CUDA 12.8
pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128

# CUDA 11.8
pip install sleap-nn[torch] --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu118

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

pip install "sleap-nn[torch]"

Info

• For more information on which CUDA version to use for your system, see the PyTorch installation guide.
  The --extra-index-url in the install command should match the CUDA version you need (e.g., https://download.pytorch.org/whl/cuda118 for CUDA 11.8, https://download.pytorch.org/whl/cuda128 for CUDA 12.8, etc.).
• On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

Verify Installation

# Test the installation
sleap-nn --help

# Check PyTorch installation
python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"

---

Installation from source

For contributing to sleap-nn or development workflows.

uv sync

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 all installed packages, you must run commands with uv run (e.g., uv run sleap-nn train ... or uv run pytest ...).

1. Clone the Repository

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

2. Install uv

macOS/LinuxWindows

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

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

3. Install Dependencies

Windows/Linux (CUDA 11.8)Windows/Linux (CUDA 12.8)macOS/CPU Only

uv sync --extra dev --extra torch-cuda118

uv sync --extra dev --extra torch-cuda128

uv sync --extra dev --extra torch-cpu

Verify Installation

In your working dir (where you ran uv sync):

# Run tests
uv run pytest tests

# Check code formatting
uv run black --check sleap_nn tests
uv run ruff check sleap_nn/

# Run CLI commands
uv run sleap-nn train ...
uv run sleap-nn track ...

---

Troubleshooting

Import Errors

If you get import errors:

1. Verify PyTorch is installed: python -c "import torch; print(torch.__version__)"
2. Try reinstalling with torch extras

CUDA Issues

If you encounter CUDA-related errors:

1. Verify your NVIDIA drivers are up to date
2. Check CUDA compatibility with PyTorch version
3. Try the CPU-only installation as a fallback

Next Steps

• Step-by-step guide on training models
• Configuration Guide
• Training models