Skip to content

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

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.

Prerequisites

Python Version Requirements

Python 3.11, 3.12, or 3.13 is required for all installation methods.

Python 3.14 is not yet supported

SLEAP currently supports Python 3.11, 3.12, and 3.13. Python 3.14 is not yet tested or supported. If you have Python 3.14 installed, you must specify --python 3.13 in your install commands.

Install uv (for uv-based methods)

If you plan to use uv tool install, uvx, uv add, or install from source, you'll need to install uv first:

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

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

Skip this step if using pip

If you're installing with pip in a conda environment, you don't need uv.

Installation methods

Choose Your Installation Method

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:

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

Platform-Specific Commands

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

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

uv tool install --python 3.13 "sleap[nn]"

uv tool install --python 3.13 "sleap"

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.

Platform-Specific Commands

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

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

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

uvx --from "sleap" sleap-label

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 add

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

Set up your project environment

Move to your project directory and initialize the virtual env: 

uv init
uv venv

Platform-Specific Commands

How uv add works

  • When you run uv init, it creates a pyproject.toml file in your working directory to manage your project's dependencies.
  • When you use uv add "sleap[nn]", it adds sleap as a dependency in your pyproject.toml and installs it in your virtual environment.
  • To add other packages, simply run uv add <package>. After adding new packages, you should run uv sync to update your environment with all dependencies specified in pyproject.toml. (or uv sync --upgrade to update all dependencies)
  • To install a local package (such as a local clone of ./sleap) in editable mode, use: 
    uv add --editable "./sleap[nn]" ...
    This is useful for development, as changes to the code are immediately reflected in your environment.

Windows: MarkupSafe Installation Issue

On Windows, you may encounter errors when running uv add "sleap[nn]" --index ... due to an incompatibility with the MarkupSafe wheel (e.g., "failed to install MarkupSafe" or similar errors).
Similar issues: #11532 and #12620.

Workaround:
Before running uv add "sleap[nn]" ... on Windows, manually install a compatible version of MarkupSafe:

uv add git+https://github.com/pallets/[email protected]

Then proceed with:

uv add "sleap[nn]" ...

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

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

uv add "sleap[nn]"

uv add "sleap"

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.13
conda activate sleap

Platform-Specific Commands

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

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

pip install "sleap[nn]"

pip install sleap

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 Dependencies

# 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

uv sync --extra dev

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.

Upgrading All Dependencies

To ensure you have the latest versions of all dependencies, use the --upgrade flag with uv sync: 

uv sync --extra dev --upgrade
This will upgrade all installed packages in your environment to the latest available versions compatible with your pyproject.toml.

Verify Installation

# Run tests
uv run pytest tests

# Check code formatting
uv run ruff check sleap tests

# Run CLI command
uv run sleap-label

Installation Notes

CUDA Version Selection

For Windows/Linux systems with NVIDIA GPUs, the installation commands above use CUDA 12.8 by default. To use a different CUDA version:

  • CUDA 11.8: Replace cu128 with cu118 in the index URL
  • CUDA 12.8: Use cu128 (default in examples above)

For more information on which CUDA version to use for your system, see the PyTorch installation guide.

macOS GPU Support

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

GUI-Only Installation

Installing sleap (without the [nn] extra) will NOT include any training/inference capabilities, as it will not include the sleap-nn backend. This should primarily be used for labeling only.

To get full functionality including training and inference, install with sleap[nn].

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

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

Using uv run with virtual environments

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

uv run sleap-label
instead of just sleap-label.

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:

# 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:

sleap-diagnostic

(Remember to use uv run sleap-diagnostic if you installed with uv add or uv sync.)

If you were not able to get SLEAP installed:

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.