LEROBOT DATASETS · VERSION DIAGNOSTIC
LeRobot dataset v2.1 or v3.0: what will load?
Separate the dataset-format version from the installed LeRobot package, diagnose version mismatches, and preserve provenance before converting an artifact.
01
Start with two different version numbers
LeRobot’s package release and a dataset’s codebase_version describe different things. A dataset can declare format v3.0 while the installed Python package is 0.6.x. Capture both, plus the immutable dataset revision, before diagnosing a failure.
A fresh upstream bug report shows why this matters: the current compatibility check can display a newer-dataset warning for an older dataset and remain silent for a newer one. Until that behavior is resolved, verify the values directly rather than trusting the warning text alone.
02
Compatibility decision table
| Dataset format | Installed code | Expected decision | Next step |
|---|---|---|---|
v2.1 | LeRobot 0.3.3-era tooling | Legacy workflow | Pin the working package and dataset revisions before changing either. |
v2.1 | LeRobot 0.4.0 and later | Conversion normally required | Expect the v2.1-to-v3.0 conversion path rather than assuming the old dataset will load unchanged. |
v3.0 | LeRobot 0.4.0 and later | Current native format | Still pin the exact package, dataset commit and metadata hashes; format compatibility does not prove policy compatibility. |
Newer dataset minor | Older codebase minor | Forward-compatibility risk | Do not rely solely on the current warning text. Inspect both versions and update only after reviewing upstream changes. |
Newer dataset major | Older codebase major | Treat as incompatible | Stop and verify upstream migration guidance. A current open bug reports that this case can be silent. |
This table is a diagnostic guide, not a substitute for the version-specific upstream release notes. A readable dataset can still be semantically incompatible with a policy.
03
Before conversion, preserve the source
- Repository and full immutable commit SHA.
- Dataset
codebase_versionfrom metadata. - Installed LeRobot package version and source revision.
- Hashes for metadata, task indexes and episode indexes.
- The original license, authorship and collection attribution.
Conversion creates a derived artifact. Record the converter command and version, configuration, output revision, file hashes, warnings and any dropped or rewritten fields. Never overwrite the only copy of the source dataset.
04
Format compatibility is not policy compatibility
Successfully opening the files does not establish that the policy receives the features it expects. Compare camera names, observation and action schemas, shapes, units, normalization statistics, timestamps, frame rate and task labels. Then preserve the runtime, calibration and evaluation protocol separately.
Read what an evaluation dataset proves—and what it does not →
05
Frequently asked questions
Is the LeRobot package version the same as the dataset-format version?
No. A package such as LeRobot 0.6.x can read a dataset whose metadata declares format v3.0. Record both values separately.
Can I load a LeRobot v2.1 dataset with current LeRobot?
Current LeRobot workflows generally require the official v2.1-to-v3.0 conversion path. Preserve the original dataset revision before converting it.
Does converting a dataset preserve its identity?
No. Conversion creates a derived artifact. Record the original revision, conversion tool and version, command or configuration, output revision and file hashes.
Does a compatible dataset format prove that a policy will work?
No. Dataset-format compatibility does not establish matching features, normalization, calibration, action semantics, runtime behavior or task success.
SOURCES
PRESERVE THE ARTIFACT