Skip to content

Installation

sleap-io can be used as a CLI tool, a Python library, or a dependency of another package. Choose the installation method that best fits your use case.

Quick Start

Run commands without installing anything:

uvx sleap-io show labels.slp
uvx sleap-io convert -i labels.slp -o labels.nwb

Requires uv. See CLI Reference for available commands.

Install as a system-wide command:

uv tool install "sleap-io[all]"

Then use:

sio show labels.slp

Add to your project:

pip install "sleap-io[all]"
# or: uv add "sleap-io[all]"

Then import:

import sleap_io as sio
labels = sio.load_file("labels.slp")

Use Cases

As a CLI utility for working with pose data

Use sleap-io to inspect, convert, and manipulate pose tracking files from the command line.

One-off usage (no installation)

The fastest way to use sleap-io is with uvx, which runs CLI tools in temporary isolated environments:

# Inspect a labels file
uvx sleap-io show labels.slp

# Convert between formats
uvx sleap-io convert -i labels.slp -o labels.nwb

# Use with all optional dependencies (requires --from for extras)
uvx --from "sleap-io[all]" sleap-io show labels.slp

This is ideal for:

  • Quick one-off conversions
  • CI/CD pipelines
  • Trying sleap-io without installing

Installing uv

If you don't have uv, install it with:

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

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

pip install uv

System-wide installation

For regular use, install sleap-io as a global tool:

uv tool install "sleap-io[all]"

uv tool install "git+https://github.com/talmolab/sleap-io.git@main"

Note

Extras cannot be specified when installing from git. Install without extras or use the PyPI version.

After installation, use either sio or sleap-io as the command:

sio show labels.slp
sio convert -i labels.slp -o labels.nwb
sio --version

The [all] extra

The [all] extra includes faster video backends (OpenCV, PyAV) and additional format support. You can omit it for a minimal installation:

uv tool install sleap-io  # Basic installation

Video support via imageio-ffmpeg is always included. The [all] extra also includes the cloud-storage adapters (s3fs, gcsfs, adlfs) needed to load .slp files from s3:///gs:///az:// URLs. Loading remote media video over http/https additionally needs a PyAV backend ([all] or [pyav]) — see Remote video.

See the CLI documentation for a complete command reference.

As a Python utility library for manipulating pose data

Use sleap-io programmatically to load, manipulate, and save pose tracking data.

In a project environment

pip install "sleap-io[all]"

uv pip install "sleap-io[all]"

uv add "sleap-io[all]"

conda install -c conda-forge sleap-io

conda extras

The conda package includes all backends by default. Optional dependencies can be installed separately if needed.

From source (latest development version)

For environments not managed by uv:

pip install "sleap-io[all]" @ git+https://github.com/talmolab/sleap-io.git@main

For quick installation into an existing virtual environment:

uv pip install "sleap-io[all] @ git+https://github.com/talmolab/sleap-io.git@main"

For uv-managed projects (adds to pyproject.toml and syncs):

uv add "sleap-io[all]" --git https://github.com/talmolab/sleap-io.git --branch main

Quick usage example

quick_demo.py
# /// script
# dependencies = ["sleap-io[all]"]
# ///
import sleap_io as sio

# Load labels from any supported format
labels = sio.load_file("labels.slp")

# Inspect the data
print(f"Videos: {len(labels.videos)}")
print(f"Labeled frames: {len(labels.labeled_frames)}")
print(f"Skeleton: {labels.skeleton.node_names}")

# Convert to numpy for analysis
locations = labels.numpy()  # shape: (frames, tracks, nodes, 2)

# Save to a different format
sio.save_nwb(labels, "labels.nwb")

Run directly with uv (no installation needed):

uv run quick_demo.py

See Examples for more usage patterns.

As a dependency of another package or tool

Add sleap-io to your project's dependencies for pose data I/O.

In pyproject.toml

[project]
dependencies = [
    "sleap-io[all]>=0.6.0",
]

[project.optional-dependencies]
pose = ["sleap-io[all]>=0.6.0"]

From source (Git dependency)

For development versions or unreleased features:

[project]
dependencies = [
    "sleap-io[all] @ git+https://github.com/talmolab/sleap-io.git@main",
]

[project]
dependencies = [
    "sleap-io[all]",
]

[tool.uv.sources]
sleap-io = { git = "https://github.com/talmolab/sleap-io.git", branch = "main" }

sleap-io[all] @ git+https://github.com/talmolab/sleap-io.git@main

Pinning specific versions

For reproducible builds, pin to a specific version or commit:

# Pin to version
"sleap-io[all]==0.6.0"

# Pin to specific commit
"sleap-io[all] @ git+https://github.com/talmolab/sleap-io.git@abc1234"

# Pin to tag
"sleap-io[all] @ git+https://github.com/talmolab/[email protected]"

As a developer looking to extend capabilities

Set up a development environment to contribute to sleap-io or add new format support.

Clone and install

# Clone the repository
git clone https://github.com/talmolab/sleap-io.git
cd sleap-io

# Install with development dependencies (recommended)
uv sync --all-extras

This installs:

  • All optional dependencies (opencv, pyav, mat, polars, cloud)
  • Development tools (pytest, ruff, mkdocs)
  • The package in editable mode

Alternative installation methods

pip install -e ".[all]"   # runtime + optional extras
pip install --group dev   # dev tools (pytest, ruff, mkdocs)

Note

dev is a PEP 735 dependency-group, not a pip extra — pip install -e ".[dev,all]" installs [all] but silently skips the dev tools (pip warns and ignores the unknown dev extra). Install the group separately with pip install --group dev.

conda env create -f environment.yml
conda activate sleap-io
pip install -e .

Running tests

# Run all tests
pytest

# Run with coverage
pytest --cov=sleap_io

# Run specific test file
pytest tests/io/test_slp.py

Code style

# Format code
ruff format

# Check linting
ruff check

# Fix auto-fixable issues
ruff check --fix

Building documentation

# Serve docs locally
mkdocs serve

# Build static site
mkdocs build

See CLAUDE.md for detailed development guidelines.

Optional Dependencies

sleap-io uses optional dependencies for specific features:

Extra Packages Purpose
opencv opencv-python Fastest video backend (2-3x faster)
pyav av Balanced speed/features video backend; required for loading remote media video over http/https
cloud s3fs, gcsfs, adlfs Load .slp from cloud-storage URLs (s3://, gs:///gcs://, az:///abfs://)
mat pymatreader LEAP .mat file support
polars polars, pyarrow Fast dataframe operations
all All of the above Everything included

http/https URLs — including Google Drive share links — work with the base install; cloud-storage URLs need the cloud extra and remote media video needs the pyav extra. See the Remote loading guide.

Install specific extras:

pip install "sleap-io[opencv]"      # Just OpenCV
pip install "sleap-io[opencv,mat]"  # Multiple extras
pip install "sleap-io[all]"         # Everything

Default video support

Video reading works out of the box via imageio-ffmpeg, which is always installed. The optional video backends provide faster performance or additional codec support.

OpenCV dependency conflicts

The opencv-python package can cause dependency conflicts in environments with other packages that also depend on OpenCV (e.g., some ML frameworks install opencv-python-headless). If you encounter conflicts, install without the opencv extra:

pip install "sleap-io[pyav,mat]"  # Skip opencv

The pyav backend provides good performance without the conflict risk.

Upgrading

CLI tool (uv tool)

uv tool upgrade sleap-io

Python package

pip install --upgrade "sleap-io[all]"

uv pip install -U "sleap-io[all]"

The -U flag allows upgrades and implies --refresh to update cached package metadata.

uv add -U "sleap-io[all]"

The -U flag upgrades the package and refreshes the lock file.

conda update -c conda-forge sleap-io

From source

# In cloned repository
git pull origin main
uv sync --all-extras

Or reinstall:

pip install --upgrade "sleap-io[all] @ git+https://github.com/talmolab/sleap-io.git@main"

Uninstalling

CLI tool (uv tool)

uv tool uninstall sleap-io

Python package

pip uninstall sleap-io

uv pip uninstall sleap-io

uv remove sleap-io

conda remove sleap-io

Troubleshooting

Video backends not found

Check installed backends:

sio --version
# Or in Python:
python -c "import sleap_io; print(sleap_io.get_available_video_backends())"

Install missing backends:

pip install opencv-python av

Import errors

Ensure you're in the correct environment:

which python
python -c "import sleap_io; print(sleap_io.__version__)"

Permission issues with uv tool

Use --python to specify a Python version:

uv tool install "sleap-io[all]" --python 3.12

Conflicting dependencies

Create a fresh environment:

uv venv
uv pip install "sleap-io[all]"

See Also