Versioning Robot Datasets: Hashes, Revisions, Reproducible Runs

A checkpoint is a directory of weights. Weights do not remember where they came from. Six weeks after a training run you have one policy that picks up the cube and one that hovers next to it, both produced from the same dataset repository, and no way to tell them apart, because that repository has been pushed to four times since.

This is not a filing problem. It is a correctness problem. If you cannot name the exact bytes a policy was trained on, you cannot reproduce a good result, you cannot bisect a bad one, and you cannot honestly say what the model learned. This article covers the mechanics: what a LeRobot dataset records about itself, how Hugging Face revisions actually behave (including the two places they behave differently from what you expect), what hashes verify, and the four-line pointer that belongs in every checkpoint you keep.

The three failures this prevents

These are not hypotheticals. Each one has a specific mechanism and a specific fix, and each one is cheap to prevent and expensive to diagnose after the fact. If you have ever filed a ticket on a policy that only works in one setup or loss that falls while the policy does nothing, at least one of these is probably in the causal chain.

That last row is documented upstream rather than folklore. NVIDIA ships a repair script in Isaac-GR00T, scripts/repair_lerobot_metadata.py, whose docstring says plainly that some Hugging Face dataset snapshots can contain episode metadata for files that are not present in the remote repo. Its job is to drop those broken episodes from meta/episodes.jsonl, update the summary fields in meta/info.json, and regenerate stats for the datasets it changed.

What a LeRobot dataset says about itself

Every LeRobot dataset carries a metadata directory. In the v3.0 layout the canonical files are meta/info.json (schema, frame rate, path templates), meta/stats.json (per-feature mean, std, min and max used for normalisation), meta/tasks.parquet (task strings mapped to integer ids) and meta/episodes/ (per-episode lengths, task ids and offsets into the shared shards, stored as chunked parquet). One caveat if you check this against the docs: the upstream v3.0 page still lists meta/tasks.jsonl, which was the v2.1 filename. The live repository tree and the docstring of LeRobotDatasetMetadata both say meta/tasks.parquet, so the doc page is the stale one. info.json is the file that claims to be a version.

# The real metadata of a public SO-101 pick-and-place dataset, at the v3.0 tag
curl -sL https://huggingface.co/datasets/lerobot/svla_so101_pickplace/resolve/v3.0/meta/info.json

{
  "codebase_version": "v3.0",
  "robot_type": "so100_follower",
  "total_episodes": 50,
  "total_frames": 11939,
  "total_tasks": 1,
  "chunks_size": 1000,
  "fps": 30,
  "splits": { "train": "0:50" },
  "data_path": "data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet",
  "video_path": "videos/{video_key}/chunk-{chunk_index:03d}/file-{file_index:03d}.mp4",
  "features": {
    "action":                { "dtype": "float32", "shape": [6], "names": ["shoulder_pan.pos", ...] },
    "observation.state":     { "dtype": "float32", "shape": [6], "names": ["shoulder_pan.pos", ...] },
    "observation.images.up":   { "dtype": "video", "shape": [480, 640, 3], "info": { ... } },
    "observation.images.side": { "dtype": "video", "shape": [480, 640, 3], "info": { ... } }
    // plus timestamp, frame_index, episode_index, index, task_index
  },
  "data_files_size_in_mb": 100,
  "video_files_size_in_mb": 500
}

Now fetch the same file from the same repository at the v2.1 tag. The episode and frame counts are identical, the robot is identical, but the storage layout is a different thing entirely. That is the point where a bare repo id stops being a description of anything.

Four ways to name a dataset, one of which is stable

A Hugging Face dataset repository is a git repository with large files kept outside the object graph. That means the whole git vocabulary applies: branches, tags, commit SHAs, and pull request refs. The revision argument in hf_hub_download, snapshot_download and LeRobotDataset all take the same set of values. What differs is how long each one keeps meaning the same thing.

The Hub exposes all of these through a single unauthenticated endpoint, which makes it trivial to snapshot the pointer state before a run. This is the single most useful command in the whole workflow, and it costs one HTTP request.

curl -s https://huggingface.co/api/datasets/lerobot/svla_so101_pickplace/refs | python3 -m json.tool

{
  "tags": [
    { "name": "v3.0", "ref": "refs/tags/v3.0",
      "targetCommit": "f641879e22172be7e8161d5e6c1503c2d2feb657" },
    { "name": "v2.1", "ref": "refs/tags/v2.1",
      "targetCommit": "e18e43de5e31997effab6abbe3810ff0e2e637d5" }
  ],
  "branches": [
    { "name": "main", "ref": "refs/heads/main",
      "targetCommit": "f641879e22172be7e8161d5e6c1503c2d2feb657" }
  ],
  "converts": [
    { "name": "parquet", "ref": "refs/convert/parquet",
      "targetCommit": "08e04aae19a9c18006d32f2e807ea23b1253ea7b" }
  ]
}

Run the same query against lerobot/pusht and the numbers stop agreeing with intuition. Its main branch points at commit 7628202a from 2025-09-27, and its v3.0 tag points at commit b1c3ecba from 2026-01-29. The tag is four months newer than the branch it looks like it should be on. Loading that dataset with revision="main" and loading it with the LeRobot default are two different requests.

Pin the dataset before the run, not after

The whole discipline is five steps, done once at the start of a run. None of them require a GPU, an account upgrade, or a tool you do not already have. This is the manual path; the platform path is in the tabs further down.

1. 1
   Resolve the pointer you were given into a SHA

   Whatever a colleague sent you, turn it into a 40-character hex string before anything else touches it. Note the full length: the Hub download helpers require the full-length hash, not an abbreviated seven-character one.

   bash

   REPO=lerobot/svla_so101_pickplace
   REF=v3.0
   
   SHA=$(curl -s "https://huggingface.co/api/datasets/$REPO/refs" \
     | python3 -c "import json,sys;d=json.load(sys.stdin);\
   print(next(t['targetCommit'] for t in d['tags']+d['branches'] if t['name']=='$REF'))")
   
   echo "$REPO @ $SHA"
   # lerobot/svla_so101_pickplace @ f641879e22172be7e8161d5e6c1503c2d2feb657

2. 2
   Download at that SHA, into a directory you control

   The hf CLI ships with huggingface_hub. Use --revision with the SHA, and --dry-run first if you want to know the transfer size before committing to it.

   bash

   pip install -U huggingface_hub
   
   hf download "$REPO" --repo-type dataset --revision "$SHA" --dry-run
   hf download "$REPO" --repo-type dataset --revision "$SHA" \
     --local-dir ./data/svla_so101_pickplace@${SHA:0:8}

3. 3
   Verify the bytes against the Hub checksums

   hf cache verify recomputes checksums for a cached snapshot and compares them to what the Hub says they should be. Turn the default warnings into failures so a partial download cannot pass silently. The same command takes --local-dir if you downloaded outside the cache.

   bash

   # Verify the cached snapshot at that exact revision
   hf cache verify "$REPO" --repo-type dataset --revision "$SHA" \
     --fail-on-missing-files --fail-on-extra-files
   
   # Or verify a directory you downloaded with --local-dir
   hf cache verify "$REPO" --repo-type dataset \
     --local-dir ./data/svla_so101_pickplace@${SHA:0:8}

4. 4
   Pass the SHA to the trainer, do not let it default

   lerobot's DatasetConfig has a revision field that defaults to None, which means the codebase version tag. Setting it explicitly is the difference between a run you can repeat and a run you cannot. Set the seed too: it defaults to 1000, but writing it down costs nothing.

   bash

   lerobot-train \
     --dataset.repo_id="$REPO" \
     --dataset.revision="$SHA" \
     --policy.type=act \
     --seed=1000 \
     --output_dir=outputs/act_${SHA:0:8}

5. 5
   Confirm the pointer landed in the checkpoint

   lerobot writes train_config.json into the checkpoint directory. Read it back and check the dataset block. If revision is null there, the checkpoint does not know what it was trained on and you have to fix that now, not in six weeks.

   bash

   python3 -c "import json;c=json.load(open('outputs/act_f641879e/train_config.json'));\
   print(c['dataset']['repo_id'], c['dataset']['revision'], c['seed'])"
   # lerobot/svla_so101_pickplace f641879e22172be7e8161d5e6c1503c2d2feb657 1000

What the hashes actually verify

A commit SHA identifies a tree, not the file contents directly. The large files in a dataset repository are stored outside git, and each one is tracked by its own content hash. You can read those hashes from the same public API, which gives you a per-file fingerprint independent of the commit.

# Per-file content hashes at two revisions of the same repository
curl -s "https://huggingface.co/api/datasets/lerobot/svla_so101_pickplace/tree/v2.1/data?recursive=true"
# 50 files, e.g. data/chunk-000/episode_000000.parquet  16271 bytes
#                oid 35926c287e3943cd647f0f32...

curl -s "https://huggingface.co/api/datasets/lerobot/svla_so101_pickplace/tree/v3.0/data?recursive=true"
# 1 file,    data/chunk-000/file-000.parquet          369943 bytes
#                oid 579ad57e2454359fa9f2c0e8...

Underneath, repositories on the Hub's Xet storage backend are deduplicated at chunk level rather than file level. Xet splits every file with content-defined chunking at roughly 64 KB per chunk, so chunk boundaries follow the content and survive an insertion anywhere in the file. New chunks are grouped into 64 MB blocks and each block is stored once in a content-addressed store. The practical consequence for dataset versioning is good: appending ten episodes to a 20 GB dataset transfers the changed chunks, not the whole file, so keeping many pinned revisions of the same dataset costs far less storage than the file sizes suggest. The consequence that catches people is that a cheap push is a frequent push, and frequent pushes are exactly what makes an unpinned pointer dangerous.

The provenance block that belongs in every checkpoint

lerobot already writes a full config snapshot next to the weights, under the filename train_config.json, and its dataset section is a serialised DatasetConfig. That dataclass carries repo_id, repo_type, root, episodes, exclude_episodes and revision, plus flags like use_imagenet_stats and streaming. The fields that matter for provenance are a short list, and every one of them is something you already know at launch time.

Two routes to the same pinned run

The manual route gives you full control and full responsibility. The platform route removes the GPU provisioning and the format juggling, but it does not remove your responsibility for the pointer. Both are laid out below for the same goal: train ACT or SmolVLA on an SO-100 dataset whose exact contents you can name a year from now.

# 1. install
pip install lerobot huggingface_hub

# 2. resolve and record the pointer
REPO=lerobot/svla_so101_pickplace
SHA=f641879e22172be7e8161d5e6c1503c2d2feb657

# 3. train against the SHA, with an explicit seed
lerobot-train \
  --dataset.repo_id=$REPO \
  --dataset.revision=$SHA \
  --policy.type=act \
  --seed=1000 \
  --output_dir=outputs/act_${SHA:0:8}

# 4. archive the resolved pointer alongside the weights
cat > outputs/act_${SHA:0:8}/PROVENANCE.txt <<EOF
dataset  $REPO@$SHA
lerobot  $(pip show lerobot | awk '/^Version/{print $2}')
seed     1000
date     $(date -u +%FT%TZ)
EOF

Conversion is where the chain quietly breaks

The moment you convert a dataset between formats, you create a second artifact that no longer has the original's commit history. This is not an edge case on this platform. GR00T N1.7 and GR00T N1.5 expect LeRobot v2.0 or v2.1, while Pi0.5, SmolVLA and ACT expect v3.0. A v3.0 dataset crashes the GR00T loader and has to be converted down. Both directions have a real script.

# Upgrade an old dataset: v2.1 -> v3.0 (lerobot)
# Pushes to main and re-tags v3.0; add --push-to-hub=false to convert in place.
python src/lerobot/scripts/convert_dataset_v21_to_v30.py --repo-id=lerobot/pusht

# Downgrade for GR00T: v3.0 -> v2 (Isaac-GR00T)
# Run from this directory: it has its own pyproject.toml, which pins lerobot to one commit.
cd scripts/lerobot_conversion
uv venv && source .venv/bin/activate
uv pip install -e . --verbose
python convert_v3_to_v2.py --repo-id BobShan/double_folding_towel_v3.0

GR00T also requires a file that plain LeRobot datasets do not have: meta/modality.json, which maps semantic field names onto index ranges in the concatenated state and action arrays, maps standardised video keys onto the actual video files, and lists annotation fields. That file is authored, not derived. If you hand-edit index ranges and do not commit the result, the exact input to your fine-tuning run exists only on the machine where you edited it.

The change that no version number catches

Here is the case that defeats every scheme described so far. lerobot pull request 777 redesigned the hardware API and, with it, the joint convention. Before it, joint values were degrees in the range -180 to 180 and the zero position for an SO-100 or SO-101 was the arm fully extended horizontally. After it, joints are normalised to -100 to 100, the gripper to 0 to 100, and zero sits in the middle of each joint's range. The upstream docs state plainly that trajectories recorded before that change replay incorrectly if loaded directly.

# From the lerobot backward-compatibility guide: fixing up a pre-PR-777 dataset
key = f"{name.removeprefix('main_')}.pos"        # key naming changed too
action[key] = action_array[i].item()

# shoulder_lift: zero moved by -90 degrees AND the direction reversed
action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90)

# elbow_flex: zero moved by -90 degrees
action["elbow_flex.pos"] -= 90

Nothing in meta/info.json distinguishes a dataset recorded on either side of that line. Both say codebase_version v3.0 after conversion. Both have six float32 action dimensions. The numbers are simply on a different convention, and a policy trained on one and deployed against the other will move to the wrong place with complete confidence. This is the same class of problem as a drifted calibration, and it is why the trainer version belongs in your provenance record next to the dataset SHA.

A dataset card that is actually enough

The documentation practice here predates robot learning. Datasheets for Datasets (Gebru and colleagues, submitted 2018, last revised December 2021) argued that every dataset should ship a document covering its motivation, composition, collection process and recommended uses, by analogy with the datasheet on an electronic component. Model Cards for Model Reporting (Mitchell and colleagues, 2018) made the parallel argument for trained models. The NeurIPS 2019 reproducibility program, reported by Pineau and colleagues, turned that into a submission checklist. None of this is exotic. For a robot dataset it collapses to a README you can write in ten minutes.

---
license: apache-2.0
task_categories: [robotics]
tags: [LeRobot, so100, pick-and-place]
---

# so100_cube_pick

| Field | Value |
|---|---|
| Frozen revision | `f641879e22172be7e8161d5e6c1503c2d2feb657` |
| Format | LeRobot v3.0 (`codebase_version` in `meta/info.json`) |
| Episodes / frames | 50 / 11939 |
| Frame rate | 30 fps |
| Arm | SO-100 follower, 6 joints |
| Cameras | `observation.images.up`, `observation.images.side`, 480x640 RGB |
| Joint convention | Normalised -100..100, gripper 0..100 (post lerobot PR #777) |
| Recorded with | lerobot <version>, <commit sha> |
| Excluded episodes | 12, 31 (operator reset mid-episode) |
| Known defects | Episodes 4-9 recorded under different lighting |

## What is NOT in here

No failure recoveries. Single cube colour. One table height.
Do not expect a policy trained on this to generalise past that.

• State the frozen revision as a full SHA, not a tag, because the tag can be recreated.
• State the joint convention in words. This is the field that saves you six months from now.
• List excluded episodes explicitly. An exclude_episodes list in a config is invisible to anyone reading the repository.
• Say what the dataset does not cover. See collecting high-quality VLA training data for what usually goes missing.
• Keep the counts. If total_episodes in the card and in meta/info.json disagree, someone pushed without updating the card.

Where this platform does not help

Honesty is cheaper than support tickets. There are five places where none of the above is solved for you, and pretending otherwise would only cost you a day later.

• Resolving a mutable pointer into a commit SHA is your step, not the platform's. Hand the training form a bare repo id and a bare repo id is all the run has to go on.
• Datasets recorded locally by the desktop client are files on your machine. They have no revision at all until you push them somewhere that gives them one.
• The v3.0 to v2.1 conversion for GR00T still has to happen, and the converted dataset is a new artifact with its own history. Nothing infers the link back to the source for you.
• GR00T's fine-tuning entry point exposes no seed, so GR00T runs are not bit-for-bit reproducible no matter how precisely you pin the data. lerobot-based training (ACT, SmolVLA, Pi0.5) does take a seed, defaulting to 1000.
• Pinning is not archiving. If the upstream Hub repository is deleted, your SHA points at nothing. Keep your own copy of anything a published result depends on.

The last one deserves emphasis because it is the one people get wrong in the direction that hurts. A commit SHA is a promise about identity, not about availability. If a result matters, mirror the dataset. If you are working from a large public corpus such as DROID, at minimum record the revision and the exact subset filter you applied, because re-deriving a subset from memory is not reproduction.

If you are starting from nothing, the order is: record a dataset following the recording tutorial, read the format notes in the dataset documentation, pin the revision, then run your first training job. The full hardware path from parts to a first imitation learning run is covered in the SO-100 complete guide, and the per-model launch details live in the training docs and the model-and-arm guides such as GR00T N1.7 on SO-100.