Installation

Installation#

SLEAP can be installed as a Python package on Windows, Linux, and Mac OS. For quick install using conda, see below:

conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a2

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

Hint

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

Open the Start menu and search for the Anaconda Prompt (if using Miniconda) or the Command Prompt if not.

Note

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

Package Manager#

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.

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:

Miniconda#

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

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

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

Installation methods#

SLEAP can be installed three different ways: via conda package, conda from source, or pip package. Select one of the methods below to install SLEAP. We recommend conda package.

This is the recommended installation method.

conda create -y -n sleap -c conda-forge -c nvidia -c sleap -c anaconda sleap=1.4.1a2

Note

  • This comes with CUDA to enable GPU support. All you need is to have an NVIDIA GPU and updated drivers.

  • If you already have CUDA installed on your system, this will not conflict with it.

  • This will also work in CPU mode if you don’t have a GPU on your machine.

Testing that things are working#

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

conda activate sleap

Hint

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.

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_develop) λ python -c "import sleap; sleap.versions()"
SLEAP: 1.2.0
TensorFlow: 2.7.1
Numpy: 1.21.5
Python: 3.7.11
OS: Windows-10-10.0.19041-SP0

GPU support#

Assuming you installed using either of the conda-based methods on Windows or Linux, SLEAP should automatically have GPU support enabled.

To check, verify that SLEAP can detect the GPUs on your system:

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

Output:

(sleap_develop) λ python -c "import sleap; sleap.system_summary()"
GPUs: 2/2 available
  Device: /physical_device:GPU:0
         Available: True
        Initalized: False
     Memory growth: None
  Device: /physical_device:GPU:1
         Available: True
        Initalized: False
     Memory growth: None

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

python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

Output:

(sleap_develop) λ python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"
[PhysicalDevice(name='/physical_device:GPU:0', device_type='GPU'), PhysicalDevice(name='/physical_device:GPU:1', device_type='GPU')]

Note

  • GPU support requires an NVIDIA GPU.

  • If you haven’t yet (or in a while), update to the latest NVIDIA drivers for your GPU.

  • We use the official conda packages for cudatoolkit and cudnn, so no external installations are required. If you already have those installed on your system, they should not interfere with the ones in the SLEAP environment.

  • TensorFlow 2.6-2.8 are compatible with CUDA Toolkit v11.3 and cuDNN v8.2.

Warning

TensorFlow 2.7+ is currently failing to detect CUDA Toolkit and CuDNN on some systems (see Issue thread).

If you run into issues, either try downgrading the TensorFlow 2.6:

pip install tensorflow==2.6.3

or follow the note below.

Note

If you are on Linux, have a NVIDIA GPU, but cannot detect your GPU:

W tensorflow/stream_executor/platform/default/dso_loader.cc:64 Could not load dynamic
library 'libcudart.so.11.0'; dlerror: libcudart.so.11.0: cannot open shared object
file: No such file or directory

then activate the environment:

conda activate sleap

and run the commands:

mkdir -p $CONDA_PREFIX/etc/conda/activate.d
echo '#!/bin/sh' >> $CONDA_PREFIX/etc/conda/activate.d/sleap_activate.sh
echo 'export SLEAP_OLD_LD_LIBRARY_PATH=$LD_LIBRARY_PATH' >> $CONDA_PREFIX/etc/conda/activate.d/sleap_activate.sh
echo 'export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH' >> $CONDA_PREFIX/etc/conda/activate.d/sleap_activate.sh
source $CONDA_PREFIX/etc/conda/activate.d/sleap_activate.sh

This will set the environment variable LD_LIBRARY_PATH each time the environment is activated. The environment variable will remain set in the current terminal even if we deactivate the environment. Although not strictly necessary, if you would also like the environment variable to be reset to the original value when deactivating the environment, we can run the following commands:

mkdir -p $CONDA_PREFIX/etc/conda/deactivate.d
echo '#!/bin/sh' >> $CONDA_PREFIX/etc/conda/deactivate.d/sleap_deactivate.sh
echo 'export LD_LIBRARY_PATH=$SLEAP_OLD_LD_LIBRARY_PATH' >> $CONDA_PREFIX/etc/conda/deactivate.d/sleap_deactivate.sh

These commands only need to be run once and will subsequently run automatically upon [de]activating your sleap environment.

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 environment named sleap:

conda env remove -n sleap

Hint

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 an 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, 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.

Contents