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. The newest version of SLEAP can always be found in the Releases page.

GPU Support

SLEAP offers GPU-accelerated training on NVIDIA GPUs (Windows/Linux) and Apple Silicon Macs (macOS). Other GPU types (such as AMD GPUs or Intel graphics) are not supported for training and may result in errors or unexpected behavior. If you do not have a supported GPU, SLEAP will automatically use CPU mode—this works for all features, but training will be significantly slower.

For more details on GPU, see the GPU Support section.

SLEAP GUI and Neural Network Backend

The SLEAP GUI for labeling can be installed and used on its own. For training and inference with neural networks, SLEAP uses the sleap-nn backend, which integrates seamlessly with the GUI (use nn extra dependency to train/ run inference).

To learn more about sleap-nn and its capabilities, visit the sleap-nn repository.

Installation methods¶

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

Choose Your Installation Method

Installation as a system-wide tool with uv: Use uv tool install to install SLEAP globally as a tool (Installation needed, strongly recommended)
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.
Installation from source: Use uv sync to install from source. (For developmental purposes)

How to open a terminal

To install SLEAP, you'll need to enter commands in a terminal. Here's how to open one on your system:

WindowsLinuxmacOS

Open the Start menu and search for Command Prompt.
Tip: You may prefer alternative terminal apps like Cmder or Windows Terminal.

Press Ctrl + Alt + T to launch a new terminal window.

Press Cmd + Space, type Terminal, and press Enter to open it.

Installation with uv tool install¶

uv tool install installs SLEAP globally as a system-wide CLI tool, making all SLEAP CLI 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 Commands¶

Windows/Linux (CUDA)Windows/Linux (CPU)macOSSLEAP GUI Only

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

Other CUDA versions

For more information on which CUDA version to use for your system, see the PyTorch installation guide. The --index 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.).

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

uv tool install "sleap[nn]"

Mac MPS support

On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

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
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 uvx¶

uvx automatically installs sleap 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 without any permanent installation.

Install uv

Install uv- an ultra-fast Python package manager:

# macOS/Linux
curl -LsSf http://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)macOSSLEAP GUI Only

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

Other CUDA versions

For more information on which CUDA version to use for your system, see the PyTorch installation guide. The --index 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.).

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

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

Mac MPS support

On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

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.

uvx Installation

Because uvx installs packages fresh on every run, it's ideal for quick one-off tests. 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 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)Windows/Linux (CPU)macOSSLEAP GUI Only

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

Other CUDA versions

For more information on which CUDA version to use for your system, see the PyTorch installation guide. The --index 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.).

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

uv pip install "sleap[nn]"

Mac MPS support

On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

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 pip install creates a .venv (virtual environment) inside your current working directory. 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 command not found or 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¶

We recommend creating a dedicated environment with conda or mamba/miniforge before installing sleap 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 python=3.12
conda activate sleap

Platform-Specific Commands¶

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

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

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.).

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

pip install "sleap[nn]"

Mac MPS support

On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

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.

Verify Installation¶

sleap-label --help

Installation from source¶

For contributing to SLEAP or development workflows.

Running With 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-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)Windows/Linux (CPU)macOSGUI Only

# CUDA 12.8
uv sync --extra dev --extra nn-cuda128 --index https://download.pytorch.org/whl/cu128 --index https://pypi.org/simple

# CUDA 11.8
uv sync --extra dev --extra nn-cuda118 --index https://download.pytorch.org/whl/cu118 --index https://pypi.org/simple

uv sync --extra dev --extra nn-cpu --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple

uv sync --extra dev --extra nn-cpu --index https://download.pytorch.org/whl/cpu --index https://pypi.org/simple

Mac MPS support

On macOS, MPS (Metal Performance Shaders) is automatically enabled for Apple Silicon acceleration.

uv sync --extra dev

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.

SLEAP uv sync Extras

The uv sync comes with the following extras (for local builds):

nn-cpu: Installs sleap-nn with the default torch-cpu backend.
nn-cuda118: Installs sleap-nn with the torch CUDA 11.8.
nn-cuda128: Installs sleap-nn with the torch CUDA 12.8.
dev: Installs all development tools for testing.
docs: Installs all documentation-related dependencies (e.g., mkdocs).
jupyter: Installs all Jupyter and JupyterLab dependencies.

Verify Installation¶

# Run tests
uv run pytest tests

# Check code formatting
uv run ruff check sleap tests

# Run CLI command
uv run sleap-label

Testing that things are working¶

If you installed using conda, first activate the sleap environment by opening a terminal and typing:

conda activate sleap

Not sure what conda environments you already installed?

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

conda env list

GUI support¶

To check that the GUI is working, simply type:

sleap-label

Using uv run

If you installed SLEAP using uv pip install or uv sync, you must prefix commands with uv run to ensure they run inside the correct virtual environment. For example, use:

uv run sleap-label

instead of just sleap-label.

You should see the SLEAP labeling interface pop up within a few moments.

Importing¶

To check if SLEAP is installed correctly in non-interactive environments, such as remote servers, confirm that you can import it with:

python -c "import sleap; sleap.versions()"

Output:

(sleap) λ python -c "import sleap; sleap.versions()"
SLEAP: 1.5.0
Numpy: 2.3.2
Python: 3.12.1
OS: macOS-14.4.1-arm64-arm-64bit

GPU support¶

Assuming you installed using either uv or the pip-based methods, SLEAP should automatically have GPU support enabled.

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

# for windows/ linux
python -c "import torch; print(torch.cuda.is_available())"

# for mac
python -c "import torch; print(torch.backends.mps.is_available())"

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 SLEAP (if installed with uv tool):

uv tool uninstall sleap

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

uv venvconda environment

# Installed with uv
# Delete `.venv/` and `uv.lock`

#For eg:
rm -rf path/to/venv
rm uv.lock

# Installed with pip in a conda env
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:

Using uv run

If you installed SLEAP using uv pip install or uv sync, you must prefix commands with uv run to ensure they run inside the correct virtual environment. For example, use:

uv run sleap-diagnostic

instead of just sleap-diagnostic.

sleap-diagnostic

If you were not able to get SLEAP installed:

Installed w/ uv:Installed w/ pip:

Run the following command on the venv (not using 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.