Download a version

For LeRobot and MCAP version downloads:

You download a saved version, never the live dataset. Saving a version gives it a name, its tag (for example 1.0), and pins its selected episodes and revisions. A preview-made version includes the saved drawing windows you published as immutable cut episodes. Later drawings, rulings or re-ingest do not change those media windows, subtasks, tags or normalization. Head has no download: publish a version first.

Without a version in the dataset reference, the command resolves the newest saved version (stable). original downloads the upload’s stored files without a version or rendering; it is described separately below.

--format	You get
lerobot_v3	A LeRobot v3 directory (default)
lerobot_v2_1	A LeRobot v2.1 directory, for loaders that predate v3
mcap_ros2	An MCAP file set with ROS 2 messages
original	Every file uploaded to the dataset, byte for byte

A version with no kept episodes has no download.

Dashboard

The dashboard gives you the CLI command for a version, ready to copy. The download itself runs in the CLI.

1. Open Datasets. On the dataset’s card, click … in its top right corner, then Download and the version’s name. Or open the dataset and click Download in its header. Both offer the newest version.
2. Choose LeRobot v3.0, LeRobot v2.1 or MCAP (ROS 2). MCAP gives one .mcap file per episode, for ROS 2 tools. A version with no robot state, or with a camera not stored as AV1 video, can’t be made into MCAP.
3. Copy the command and run it on the machine the dataset should go to.

The first time, install the CLI and run qualia auth login with an API key from your workspace’s Settings → API keys.

Download stays disabled until the dataset has a version. To save one on an upload or merged dataset, click Publish, choose the include groups, and use Apply all to freeze and measure its saved drawings. Review omissions, then name it and choose Create version. Review need not be complete; Kept by a person is the default selection. A mixture instead tags its resolved head. See Publish a version.

For an older version, open the dataset’s versions tab, which lists every tag, newest first (Current is the head), and click the tag. Its version page has the same Download section. Open Version details there to copy the DatasetVersion id or read the version reference, such as my-dataset:1.0. Head has no DatasetVersion id.

CLI

qualia dataset pin saves the version and prints its DatasetVersion id. Use the dataset slug or UUID before the colon in qualia dataset download:

qualia dataset pin <DATASET_UUID> 1.0 --note "first cut"
# Pinned DatasetVersion <DATASET_VERSION_UUID> (<DATASET>:1.0, 120 episode(s))

# LeRobot v3, the newest version (stable)
qualia dataset download my-dataset

# LeRobot v3, version 1.0
qualia dataset download my-dataset:1.0

# LeRobot v2.1
qualia dataset download my-dataset:1.0 --format lerobot_v2_1

# MCAP with ROS 2 messages
qualia dataset download my-dataset:1.0 --format mcap_ros2

# Every file uploaded, byte for byte
qualia dataset download my-dataset --format original

The folder defaults to ./<slug>-<tag>, with -v21 or -mcap added for those formats, and to ./<slug>-original for original; pass a second argument to choose it. A spinner shows while the server builds the version (or, for original, lists the files), then a bar with bytes, speed and files. The command ends with a line such as Saved my-dataset:1.0 as mcap_ros2 to /home/me/my-dataset-1.0-mcap (12 files, 1.2 GB). Files are checked as they arrive, and running the command again after a stop fetches only what is missing.

original is every file uploaded to the dataset, byte for byte, with no version involved. It also holds what ingest stored beside those files: the annotations under meta/qds, meta/ingest_report.json and, for an MCAP upload, the LeRobot data and videos ingest made from the recordings. Trims and splits are not applied: the takes are whole, and a split’s pieces are only annotations under meta/qds. When the dataset has any, the command says how many on stderr and how to get the curated episodes (tag a version, then download it). Only an upload has files of its own, so a merged dataset or a mixture is refused: download one of its uploads, or a version. For now original needs an organization key; a workspace key is refused.

An MCAP download keeps only what was mapped at upload, so tf, diagnostics and custom topics do not come back; use original when you need them byte for byte.

Tagging and resolving <dataset>:<tag> act in the API key’s own account. See qualia dataset download.

The first download of a version in a format starts its rendering, which needs a key that can write to the dataset (data:write). Once it is rendered, downloads of it in that format need read access only (data:read). The command also accepts a full accounts/<account>/datasets/<dataset>/versions/<tag> name. The dashboard’s Download line names the version by its reference. head has no download: pin a tag first.

SDK

from qualia import Qualia

client = Qualia()

result = client.data.download(
    "my-dataset:1.0",
    "./my-dataset-1.0",
    format="lerobot_v3",  # or "lerobot_v2_1", "mcap_ros2"
)
print(result.destination, result.file_count)

# every file uploaded, byte for byte (no version)
result = client.data.download("my-dataset", format="original")

See Download a version.

When a download is refused

A version that contains a blocked episode (a NaN, an infinity, a missing value or a wrong width in its state or action rows) is refused, because a download carries every episode. Publish a curated version without those episodes as a new dataset, then download that version. See qualia dataset curate. --format original is not refused: it renders nothing, so it downloads the upload’s files, blocked episodes included.