Installation¶

Documentation for New SLEAP Versions

This documentation is for the latest version of SLEAP.
If you are using SLEAP version 1.4.1 or earlier, please visit the legacy documentation.

SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. For a quick sample using uv- an ultra-fast Python package and project manager, see below (no installation required!):

Windows/Linux (CUDA 12.8)macOS/CPU OnlySLEAP GUI Only

uvx --from "sleap[nn]" --index-url https://pypi.org/simple --extra-index-url https://download.pytorch.org/whl/cu128 sleap-label

Other CUDA versions

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.

uvx --from "sleap[nn]" sleap-label

uvx --from "sleap" sleap-label

GUI ONLY

Installing this version of SLEAP will NOT include any training/inference capabilities, as it will not include the sleap-nn backend. This should primarily be used for labeling.

Sample with uvx

Note that opening SLEAP w/ uvx will not install SLEAP onto your system, it will only 'invoke' SLEAP.

For more in-depth installation instructions, see the installation methods. The newest version of SLEAP can always be found in the Releases page.

Note

SLEAP currently supports GPU-accelerated training on NVIDIA GPUs and Apple Silicon Macs. Training on other GPU architectures (e.g., AMD GPUs and older Macs) is not supported and may lead to failures or unexpected behavior. If no supported GPU is available, SLEAP can still run in CPU mode, but training speed may be reduced.

For detailed GPU setup instructions, see gpu-support.

Note

For labeling purposes, the SLEAP GUI can be installed on its own. However, sleap-nn is a neural network backend available for training and inference w/ the SLEAP GUI.

For more details on this backend, see sleap-nn.

Installation methods¶

How to open a terminal:

Installation requires entering commands in a terminal. To open one:

WindowsLinuxMac OS

Open the Start menu and search for the Command Prompt.

Note

On Windows, our personal preference is to use alternative terminal apps like Cmder or Windows Terminal.

Launch a new terminal by pressing Ctrl + Alt + T.

Launch a new terminal by pressing Cmd + Space and searching for Terminal.

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

Choose Your Installation Method

Installation with as a system-wide tool with uv: Use uv tool install to install SLEAP globally as a tool (Installation needed, strongly recommended)
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 with uv tool install¶

uv tool install automatically installs and creates the sleap-label tool inside a virtual environment located inside the uv tool directory. This means that running this global tool will use this installed version.

First Time uv Setup

Install uv first - an ultra-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)macOS/CPU OnlySLEAP GUI Only

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

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

Other CUDA versions

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.

uv tool install "sleap[nn]"

uv tool install "sleap"

GUI ONLY

Installing this version of SLEAP will NOT include any training/inference capabilities, as it will not include the sleap-nn backend. This should primarily be used for labeling.

How uv tool install Works

Automatic Installation: Downloads and installs SLEAP with dependencies
Isolated Environment: Each run after installation runs in a clean, separated virtual environment
No Conflicts: Won't interfere with your existing Python packages/dependencies
Uses Recent Packages: Uses the latest version from PyPI

Verify Installation¶

# Test the installation
sleap-label --help

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 using uv pip.

Install and set-up uv

Step-1: Install uv - an ultra-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 Commands¶

Windows/Linux (CUDA)macOS/CPU OnlySLEAP GUI Only

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

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

Other CUDA versions

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.

uv pip install "sleap[nn]"

uv pip install "sleap"

GUI ONLY

Installing this version of SLEAP will NOT include any training/inference capabilities, as it will not include the sleap-nn backend. This should primarily be used for labeling.

Running With uv run

uv sync & uv pip install 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-label ... or uv run pytest ...) with these installation methods.

Verify Installation¶

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

SLEAP 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-label --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¶

SLEAP requires many complex dependencies, so we strongly recommend using a package manager such as Miniforge or Miniconda to install SLEAP in its own isolated environment, if not using uv.

Note

If you already have Anaconda on your computer (and it is an older installation), then make sure to set the solver to libmamba in the base environment.

conda update -n base conda
conda install -n base conda-libmamba-solver
conda config --set solver libmamba

Warning

Any subsequent conda commands in the docs will need to be replaced with mamba if you have Mamba installed instead of Anaconda or Miniconda.

If you don't have a conda package manager installation, here are some quick install options:

Miniforge¶

Miniforge is a minimal installer for conda that includes the conda package manager and is maintained by the conda-forge community. The only difference between Miniforge and Miniconda is that Miniforge uses the conda-forge channel by default, which provides a much wider selection of community-maintained packages.

WindowsLinuxMac (Apple Silicon)Mac (Intel)

Open a new PowerShell terminal (does not need to be admin) and enter:

Invoke-WebRequest -Uri "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe" -OutFile "$env:UserProfile/Downloads/Miniforge3-Windows-x86_64.exe"; Start-Process -FilePath "$env:UserProfile/Downloads/Miniforge3-Windows-x86_64.exe" -ArgumentList "/InstallationType=JustMe /RegisterPython=1 /S" -Wait; Remove-Item -Path "$env:UserProfile/Downloads/Miniforge3-Windows-x86_64.exe"

Open a new terminal and enter:

curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -o "$HOME/Downloads/Miniforge3-Linux-x86_64.sh" && chmod +x "$HOME/Downloads/Miniforge3-Linux-x86_64.sh" && "$HOME/Downloads/Miniforge3-Linux-x86_64.sh" -b -p "$HOME/miniforge3" && rm "$HOME/Downloads/Miniforge3-Linux-x86_64.sh" && "$HOME/miniforge3/bin/conda" init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc"

Open a new terminal and enter:

curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh -o "$HOME/Downloads/Miniforge3-MacOSX-arm64.sh" && chmod +x "$HOME/Downloads/Miniforge3-MacOSX-arm64.sh" && "$HOME/Downloads/Miniforge3-MacOSX-arm64.sh" -b -p "$HOME/miniforge3" && rm "$HOME/Downloads/Miniforge3-MacOSX-arm64.sh" && "$HOME/miniforge3/bin/conda" init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc"

Open a new terminal and enter:

curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh -o "$HOME/Downloads/Miniforge3-MacOSX-x86_64.sh" && chmod +x "$HOME/Downloads/Miniforge3-MacOSX-x86_64.sh" && "$HOME/Downloads/Miniforge3-MacOSX-x86_64.sh" -b -p "$HOME/miniforge3" && rm "$HOME/Downloads/Miniforge3-MacOSX-x86_64.sh" && "$HOME/miniforge3/bin/conda" init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc"

Miniconda¶

This is a minimal installer for conda that includes the conda package manager and is maintained by the Anaconda company.

WindowsLinuxMac (Apple Silicon)Mac (Intel)

Open a new PowerShell terminal (does not need to be admin) and enter:

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o miniconda.exe; Start-Process -FilePath ".\miniconda.exe" -ArgumentList "/S" -Wait; del miniconda.exe

Open a new terminal and enter:

mkdir -p "$HOME/miniconda3" && wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O "$HOME/miniconda3/miniconda.sh" && bash "$HOME/miniconda3/miniconda.sh" -b -u -p "$HOME/miniconda3" && rm "$HOME/miniconda3/miniconda.sh" && "$HOME/miniconda3/bin/conda" init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc"

Open a new terminal and enter:

curl -fsSL --compressed https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o "$HOME/Downloads/Miniconda3-latest-MacOSX-arm64.sh" && chmod +x "$HOME/Downloads/Miniconda3-latest-MacOSX-arm64.sh" && "$HOME/Downloads/Miniconda3-latest-MacOSX-arm64.sh" -b -u -p "$HOME/miniconda3" && rm "$HOME/Downloads/Miniconda3-latest-MacOSX-arm64.sh" && "$HOME/miniconda3/bin/conda" init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc"

Open a new terminal and enter:

curl -fsSL --compressed https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o "$HOME/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" && chmod +x "$HOME/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" && "$HOME/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" -b -u -p "$HOME/miniconda3" && rm "$HOME/Downloads/Miniconda3-latest-MacOSX-x86_64.sh" && "$HOME/miniconda3/bin/conda" init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc"

See the Miniconda website for up-to-date installation instructions if the above instructions don't work for your system.

SLEAP can be installed with pip via pip package. See below.

This is the recommended method for Google Colab.

Note

Requires Python 3.11+

Although you do not need Miniconda installed to perform a pip install, we recommend installing Miniconda to create a new environment where we can isolate the pip install. Alternatively, you can use a virtual environment (venv) if you have an existing Python 3.11+ installation. If you are working on Google Colab, skip to step 3 to perform the pip install without using a conda environment.

Note

Otherwise, create a new conda environment where we will pip install sleap:
```
conda create --name sleap python=3.11
```
Then activate the environment to isolate the pip install from other environments on your computer:
```
conda activate sleap
```
Warning

Refrain from installing anything into the base environment. Always create a new environment to install new packages.

Platform-Specific Installation¶

Windows/Linux (CUDA)macOS/CPU OnlySLEAP GUI Only

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

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

pip install sleap[nn-cpu]

pip install sleap

Note

The pypi distributed package of SLEAP ships with the following extras:

dev: This installs all jupyter dependencies and developement tools for testing and building docs.
docs: This installs all docs-related dependencies (ex. mkdocs).
nn-cpu: This installs sleap-nn with torch-cpu.
nn-gpu: This installs sleap-nn with torch-cuda128.
jupyter: This installs all pypi and jupyter lab dependencies.

Verify Installation¶

sleap-label --help

Development Setup with uv¶

For contributing to SLEAP or development workflows.

Running With uv run

uv sync & uv pip install 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-label ... or uv run pytest ...) with these installation methods.

1. Clone the Repository

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

2. Install uv (skip if already installed)

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 12.8)macOS/CPU OnlyGUI Only

uv sync --extra dev --extra nn-gpu

uv sync --extra dev --extra nn-cpu

uv sync --extra dev

SLEAP uses PyTorch for GPU acceleration. To directly check if PyTorch is detecting your GPUs:

python -c "import torch; print(torch.cuda.is_available())"

Output:

(sleap) λ python -c "import torch; print(torch.cuda.is_available())"
False

# Test run on Apple Silicon architecture

macOS MPS Support

Even with [nn-cpu] when installing SLEAP, macOS automatically enables MPS (Metal Performance Shaders) for Apple Silicon acceleration via sleap-nn backend.

Upgrading and uninstalling¶

We strongly recommend installing SLEAP in a fresh environment when updating. This is because dependency versions might change, and depending on the state of your previous environment, directly updating might break compatibility with some of them.

To uninstall an existing uv venv or conda environment named sleap:

uv venvconda environment

# Installed with uv
rm -rf path/to/venv
rm -rf path/to/uv.lock

# Installed with pip
conda env remove -n sleap

Not sure what conda environments you already installed?

You can get a list of the environments on your system with:

conda env list

Once the environment has been removed, you are free to install SLEAP using any of the installation methods above into a venv or conda environment of the same name.

Getting help¶

If you run into any problems, check out the Github Discussions and GitHub Issues to see if others have had the same problem.

If you get any errors or the GUI fails to launch, try running the diagnostics to see what SLEAP is able to detect on your system:

sleap-diagnostic

If you were not able to get SLEAP installed:

Installed w/ uv:Installed w/ pip:

Run the following command on the venv created by uv tool install:

uv pip list

Activate the conda environment it is in and generate a list of the package versions installed:

conda list

Then, open a new Issue providing the versions from either command above, as well as any errors you saw in the console during the installation. Or start a discussion to get help from the community.