LeRobot Dataset v2.1 vs v3.0: What Changed, How to Convert

Two LeRobot dataset formats are in active use, and the difference is not cosmetic. A v2.1 LeRobot dataset is one Parquet file and one MP4 per episode. A v3.0 dataset packs many episodes into shared files and rebuilds the episode boundaries out of metadata. Feed the wrong one to the wrong trainer and you get a stack trace, a FileNotFoundError on a file that has not existed since 2025, or, quietest of the three, a run that trains against normalization statistics that no longer describe the data.

This is the practical version: which files each version has, which trainer accepts which, the commands for both conversion directions, and what happens to meta/stats.json on the way. Everything below was checked against lerobot v0.6.1 (released 3 August 2026) and the Isaac-GR00T main branch as read on 23 August 2026. Where a path or a default has already changed once, that is called out.

Three versions, and the files that tell them apart

You can identify a LeRobot dataset without opening a single Parquet file. Look at meta/. Every version rearranged that folder, and every rearrangement removed something the previous one relied on. The table below is not from the docs. It is the HTTP status of each file on the public reference dataset lerobot/pusht, fetched at three Hub revisions on 23 August 2026.

# Which format is this dataset in? Ask, do not guess.
curl -s https://huggingface.co/datasets/lerobot/pusht/raw/main/meta/info.json \
  | python -c "import json,sys; print(json.load(sys.stdin)['codebase_version'])"
# v3.0

# The same repo still serves the older layout as a git revision:
curl -s https://huggingface.co/datasets/lerobot/pusht/raw/v2.1/meta/info.json \
  | python -c "import json,sys; print(json.load(sys.stdin)['codebase_version'])"
# v2.1

# Locally, for a dataset you recorded yourself:
python -c "import json; print(json.load(open('meta/info.json'))['codebase_version'])"

The stats.json that vanished and came back

The row worth staring at is stats.json. v2.0 had one global statistics file. v2.1 deleted it in favour of per-episode statistics in episodes_stats.jsonl, so episodes could be added or filtered without invalidating the constants for the whole dataset. v3.0 kept the per-episode statistics, moved them into the episodes Parquet as columns prefixed stats/, and brought the aggregated file back.

That zigzag causes most conversion confusion, because a strict v2.1 dataset has no global stats file at all. Any consumer that opens meta/stats.json and asserts on it, which is exactly what the GR00T loader does, fails on a clean v2.1 dataset even though the version number is the one it asked for. The format version and the file set are not the same question.

What v3.0 actually changed

v2.1                                             v3.0
----                                             ----
data/chunk-000/episode_000000.parquet            data/chunk-000/file-000.parquet
data/chunk-000/episode_000001.parquet              (many episodes per file)
...
videos/chunk-000/observation.image/              videos/observation.image/chunk-000/
        episode_000000.mp4                               file-000.mp4
meta/info.json                                   meta/info.json
meta/episodes.jsonl                              meta/episodes/chunk-000/file-000.parquet
meta/episodes_stats.jsonl                          (folded into the same parquet)
meta/tasks.jsonl                                 meta/tasks.parquet
(no stats.json)                                  meta/stats.json

• One episode per file became many episodes per file. Episode boundaries are byte and frame offsets in metadata, not filenames.
• Metadata moved from JSON Lines to Parquet: meta/episodes/ is chunked Parquet, meta/tasks.parquet replaces meta/tasks.jsonl.
• info.json lost total_chunks and total_videos, and gained data_files_size_in_mb and video_files_size_in_mb.
• Streaming arrived. StreamingLeRobotDataset iterates a Hub repo without downloading it, and lerobot-train accepts --dataset.streaming=true.

Which trainer accepts which version

Here the format question stops being academic. The five trainable policies on AY-Robots split down the middle, and the split is a property of each vendor's data loader rather than of the platform.

The v3.0 side is simply lerobot itself. Any lerobot from v0.4.0 (23 October 2025) onward sets CODEBASE_VERSION to "v3.0" and runs every dataset through check_version_compatibility, which raises on a major mismatch. Pi0.5, SmolVLA and ACT inherit the requirement from the framework. GR00T has its own loader, and it is worth seeing why a v3.0 tree cannot satisfy it.

# Isaac-GR00T: gr00t/data/dataset/lerobot_episode_loader.py
LEROBOT_INFO_FILENAME = "info.json"
LEROBOT_EPISODES_FILENAME = "episodes.jsonl"
LEROBOT_TASKS_FILENAME = "tasks.jsonl"
LEROBOT_MODALITY_FILENAME = "modality.json"
LEROBOT_STATS_FILE_NAME = "stats.json"
LEROBOT_RELATIVE_STATS_FILE_NAME = "relative_stats.json"

# ... later, in the metadata loader:
stats_path = meta_dir / LEROBOT_STATS_FILE_NAME
assert stats_path.exists(), (
    f"{stats_path} does not exist for {self.dataset_path}, please use gr00t/data/stats.py to generate it"
)

So this is not a version check you can override with a flag. The loader opens meta/episodes.jsonl with a bare open() call, and a v3.0 tree has no such file. That is why a v3.0 dataset must be converted down before fine-tuning a GR00T model, and why there is a dedicated failure page at dataset rejected because it is v3.0.

Converting up: v2.1 to v3.0

The upward converter ships inside lerobot. It is not a console entry point, so you invoke it as a module. Mind the path: it was lerobot.datasets.v30.convert_dataset_v21_to_v30 through v0.5.0 and moved to lerobot.scripts.convert_dataset_v21_to_v30 in v0.5.1. The Hugging Face announcement post still prints the old path; the error message lerobot raises today prints the new one. Only the second spelling works on anything current.

1. 1
   Install lerobot with the dataset extra

   Conversion needs jsonlines, pyarrow and the datasets stack, which sit behind the dataset extra rather than the base install.

   bash

   python -m venv .venv && source .venv/bin/activate
   pip install "lerobot[dataset]>=0.4.0"
   lerobot-info   # prints python, torch and ffmpeg versions

2. 2
   Confirm the source really is v2.1

   The converter calls validate_local_dataset_version and refuses anything else. A v2.0 dataset fails here, not halfway through.

   bash

   python -c "import json; print(json.load(open('/data/so100_pickplace/meta/info.json'))['codebase_version'])"
   ls /data/so100_pickplace/meta/
   # expect: info.json episodes.jsonl episodes_stats.jsonl tasks.jsonl

3. 3
   Convert locally, with the Hub explicitly disabled

   For this script --root is the exact dataset folder containing meta/, data/ and videos/. Setting --push-to-hub=false is the important part, and it is not the default.

   bash

   python -m lerobot.scripts.convert_dataset_v21_to_v30 \
     --repo-id you/so100_pickplace \
     --root /data/so100_pickplace \
     --push-to-hub=false

4. 4
   Check what it left behind

   The original tree is moved to a sibling folder with an _old suffix and the converted tree takes the original path. Your v2.1 copy is not deleted, but it is not where you left it.

   bash

   ls -d /data/so100_pickplace*
   # /data/so100_pickplace       <- now v3.0
   # /data/so100_pickplace_old   <- the original v2.1 tree
   
   find /data/so100_pickplace/meta -type f | sort

5. 5
   Tune the shard size only if you have a reason

   Larger shards mean fewer files and faster init, smaller shards mean cheaper partial downloads.

   bash

   python -m lerobot.scripts.convert_dataset_v21_to_v30 \
     --repo-id you/so100_pickplace \
     --root /data/so100_pickplace \
     --data-file-size-in-mb 100 \
     --video-file-size-in-mb 200 \
     --push-to-hub=false

If your dataset is still v2.0

The upward converter reads meta/episodes_stats.jsonl, which a v2.0 dataset does not have. Worse, v2.0 gets no helpful error anywhere in the chain: BackwardCompatibilityError only formats a message for version 2.1 and raises NotImplementedError for everything else, so a v2.0 tree handed to lerobot fails with a bare pointer at the Discord. The obvious fix, running the v2.0 to v2.1 converter first, has a catch: that script was removed from lerobot after v0.3.3. It is still fetchable at that tag, so the workaround is a throwaway environment pinned to the old release for one hop.

# Hop 1: v2.0 -> v2.1, in a pinned throwaway env
python -m venv .venv-021 && source .venv-021/bin/activate
pip install "lerobot==0.3.3"
python -m lerobot.datasets.v21.convert_dataset_v20_to_v21 --repo-id you/so100_pickplace
deactivate

# Hop 2: v2.1 -> v3.0, in a current env
source .venv/bin/activate
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
  --repo-id you/so100_pickplace --root /data/so100_pickplace --push-to-hub=false

Converting down: v3.0 to v2.1 for GR00T

The downward converter is not in lerobot. NVIDIA ships it inside Isaac-GR00T at scripts/lerobot_conversion/convert_v3_to_v2.py, with its own pyproject.toml, because it needs a lerobot install while the repo root installs the gr00t package instead. It is purely local: there is no --push-to-hub flag, which is a mercy after the previous section.

1. 1
   Set up the conversion subproject

   Run this from inside scripts/lerobot_conversion, not from the repo root. Installing from the root gets you gr00t and not the converter's dependencies.

   bash

   git clone https://github.com/NVIDIA/Isaac-GR00T.git
   cd Isaac-GR00T/scripts/lerobot_conversion
   uv venv && source .venv/bin/activate
   uv pip install -e . --verbose
   ffmpeg -version   # hard requirement, the script shells out to it

2. 2
   Run the converter

   Careful with --root. This script does root = Path(root) / repo_id, so it wants the parent directory, the opposite of lerobot's converter.

   bash

   python convert_v3_to_v2.py \
     --repo-id you/so100_pickplace \
     --root /data
   
   # Omit --root entirely and it downloads a fresh snapshot
   # from the Hub into $HF_LEROBOT_HOME/you/so100_pickplace

3. 3
   Check the swap it performed

   Like the upward script it converts in place. The original v3.0 tree moves to a sibling with a _v3.0 suffix and the reconstructed v2.1 tree takes the original path.

   bash

   ls -d /data/you/so100_pickplace*
   # .../so100_pickplace        <- now v2.1
   # .../so100_pickplace_v3.0   <- the original
   
   ls /data/you/so100_pickplace/meta/
   # info.json  episodes.jsonl  episodes_stats.jsonl  tasks.jsonl  stats.json

4. 4
   Add meta/modality.json yourself

   The converter never writes it. GR00T needs it to know which slice of the state and action vectors is which joint, and which camera key maps to which model input. Start from demo_data/cube_to_bowl_5/meta/modality.json in the repo.

   json

   {
     "state":  { "single_arm": {"start": 0, "end": 5}, "gripper": {"start": 5, "end": 6} },
     "action": { "single_arm": {"start": 0, "end": 5}, "gripper": {"start": 5, "end": 6} },
     "video":  { "webcam": {"original_key": "observation.images.front"} },
     "annotation": { "human.task_description": {} }
   }

5. 5
   Regenerate the statistics GR00T actually reads

   A tyro CLI, so run --help once to confirm how your checkout spells the embodiment tag enum. A six-axis arm that is not a built-in embodiment also needs a modality config module.

   bash

   cd ../..   # back to the Isaac-GR00T root
   python -m gr00t.data.stats --help
   
   python -m gr00t.data.stats \
     --dataset-path /data/you/so100_pickplace \
     --embodiment-tag new_embodiment \
     --modality-config-path examples/SO100/so100_config.py

The statistics, and what actually survives

Normalization statistics are the part of a dataset that fails quietly. A wrong path throws. A wrong mean shifts every input the policy sees by a constant and hands you a run that converges to something plausible and useless.

Read across and the answer falls out. The upward converter recomputes nothing: it folds your existing episodes_stats.jsonl into the stats/ columns of meta/episodes/ and re-aggregates it into a fresh meta/stats.json. Statistics that were already wrong stay wrong in a new file format. The reference dataset shows the consequence: every feature in lerobot/pusht's v3.0 meta/stats.json carries exactly count, max, mean, min and std, not one quantile, because the v2.1 stats it was built from had none to forward. Going the other way, NVIDIA's script unflattens those columns back into episodes_stats.jsonl and copies meta/stats.json byte for byte, and GR00T then throws that copy away: any feature missing one of its six required fields, mean, std, min, max, q01 and q99, is stale and gets recomputed.

# LeRobot side: recompute from scratch over all episodes.
# Without --operation.overwrite it writes to <repo_id>_recomputed_stats.
lerobot-edit-dataset \
  --repo_id you/so100_pickplace \
  --new_repo_id you/so100_pickplace \
  --operation.type recompute_stats \
  --operation.overwrite true

# GR00T side: force a full recompute by deleting the cache first.
rm -f /data/you/so100_pickplace/meta/stats.json \
      /data/you/so100_pickplace/meta/relative_stats.json
python -m gr00t.data.stats \
  --dataset-path /data/you/so100_pickplace \
  --embodiment-tag new_embodiment \
  --modality-config-path examples/SO100/so100_config.py

Do it yourself, or do it on AY-Robots

Pre-flight checklist

1. Read codebase_version out of meta/info.json. Do not infer the version from directory shape.
2. List meta/ and compare against the file table above. A valid version number with a missing file is the common surprise.
3. If the dataset came from the Hub, look for a revision tag in the version you need before running any converter.
4. Decide the direction from the trainer: GR00T N1.7 and GR00T N1.5 need v2.0 or v2.1, everything else needs v3.0.
5. Copy the dataset first. Both scripts convert in place and rename the original out from under you.
6. Pass --push-to-hub=false unless you specifically intend to rewrite the Hub repo.
7. Write meta/modality.json for any GR00T-bound dataset and check the index ranges against your arm's degrees of freedom.
8. Delete meta/stats.json and regenerate whenever calibration, joint order or camera keys changed, then watch the first few hundred training steps before walking away.

If you are still choosing between the two camps rather than converting between them, the head-to-head at GR00T N1.7 against Pi0.5 puts the numbers side by side, and the SO-100 setup guide covers everything upstream of the dataset. The full format description lives in the dataset docs.