Skip to content

sleap-io

CI codecov Release PyPI - Python Version PyPI

A standalone Python library and CLI for working with animal pose tracking data. Read, write, convert, and manipulate pose data across formats with minimal dependencies.

Complements the core SLEAP package but does not include labeling, training, or inference.

Features

  • Multi-format I/O -- Read and write SLEAP, NWB, COCO, DeepLabCut, Ultralytics YOLO, JABS, Label Studio, CSV, Analysis HDF5, AlphaTracker, and LEAP formats
  • CLI tools -- Inspect, convert, render, and transform data from the command line (reference)
  • Rendering -- Produce publication-quality videos and images with pose overlays, customizable colors, markers, motion trails, and presets (guide)
  • Transforms -- Crop, scale, rotate, pad, and flip videos with automatic coordinate adjustment (guide)
  • Merging -- Combine annotations from multiple sources with flexible matching strategies (guide)
  • Codecs -- Convert to/from NumPy arrays, DataFrames (pandas/polars), and dictionaries (guide)
  • Video I/O -- Read any video format via pluggable backends (FFMPEG, OpenCV, PyAV) with a NumPy-like interface (model)
  • Lazy loading -- Load large SLP files up to 90x faster by deferring object creation (details)
  • Remote URLs -- Load .slp/.pkg.slp and remote media video directly from https://, s3://, gs://, az://, and Google Drive URLs with lazy range-based reads and optional persistent caching (guide)
  • Dataset splits -- Create train/val/test splits and export to formats like Ultralytics YOLO (example)

Installation

pip install "sleap-io[all]"

Or use without installing:

uvx sleap-io show labels.slp

See Installation for all options including uv, conda, CLI tool install, and development setup.

Quick start

CLI

sio show labels.slp                                    # Inspect a file
sio convert -i labels.slp -o labels.nwb                # Convert formats
sio render -i predictions.slp -o output.mp4            # Render video
sio transform labels.slp --scale 0.5 -o scaled.slp    # Transform

Python

import sleap_io as sio

# Load and convert between formats
labels = sio.load_file("predictions.slp")
labels.save("predictions.nwb")

# Convert to NumPy arrays
trx = labels.numpy()  # (n_frames, n_tracks, n_nodes, 2); n_frames spans up to the last labeled frame

# Merge annotations from multiple sources (track matching defaults to identity;
# pass track="name" to merge tracks by name — see the Merging guide)
base = sio.load_file("manual_annotations.slp")
base.merge(sio.load_file("predictions.slp"))
base.save("merged.slp")

See Examples for more recipes including creating labels from scratch, NWB export, rendering, skeleton replacement, and YOLO/COCO export.

Support

For technical inquiries, please open an Issue.

For general SLEAP usage, see sleap.ai.

License

BSD 3-Clause License. See LICENSE for details.