Publishing a Robot Dataset on Hugging Face: Repo, Card, Licence

Published is not the same as uploaded

Uploading a LeRobot dataset takes one flag. Publishing one takes an afternoon. The difference shows up three months later, when somebody else, or you, tries to reproduce the run and cannot answer basic questions: which arm, which cameras, which firmware, how many episodes were thrown away and why, and whether the number in the card counts the deleted ones.

Most public robot datasets are uploads. They have data, they load, and the card says This dataset was created using LeRobot and nothing else. That is enough to train on and not enough to trust. This article is about the gap: what the repo actually contains, what the card has to say for a stranger to repeat your run, and which licence choice you are making without noticing. It assumes you already have episodes on disk; if you do not, start with recording your first dataset and with what makes VLA training data good in the first place.

What is actually inside the repo

A LeRobot dataset repo is not a folder of videos. It is a schema plus shards plus a metadata layer that reconstructs episode boundaries, as the dataset documentation describes. In v3.0 the episode is no longer a file; it is a range of rows and a byte offset recorded in metadata, which is why deleting a file by hand corrupts the dataset in a way that is hard to see.

The defaults in src/lerobot/datasets/utils.py are worth knowing because they determine how your repo looks to a downloader: DEFAULT_CHUNK_SIZE = 1000 files per chunk directory, DEFAULT_DATA_FILE_SIZE_IN_MB = 100 and DEFAULT_VIDEO_FILE_SIZE_IN_MB = 200. Those are the values used when a dataset is created. They are not a contract: every dataset writes its own numbers into info.json, so a repo built under an older default keeps that older default forever.

my-user/so100-cube-to-bowl/
  README.md                          <- the card, YAML + prose
  meta/
    info.json                        <- codebase_version, fps, robot_type, features
    stats.json                       <- normalisation statistics
    tasks.parquet                    <- task strings -> ids  (v2.1: tasks.jsonl)
    episodes/chunk-000/file-000.parquet
  data/
    chunk-000/file-000.parquet       <- many episodes per file in v3.0
  videos/
    observation.images.front/chunk-000/file-000.mp4
    observation.images.wrist/chunk-000/file-000.mp4

Getting it onto the Hub

The path most people take is that lerobot-record uploads at the end of the session. That is fine, and it is also why so many half-finished datasets exist: the upload happens before you have looked at the data. The sequence below separates recording from publishing on purpose.

1. 1
   Authenticate with a write token

   Create the token at Settings, Access Tokens on huggingface.co with write access. Never paste it into a notebook you will commit.

   bash

   hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
   
   HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
   echo $HF_USER

2. 2
   Record without pushing

   Add --dataset.push_to_hub=False so nothing leaves the machine yet. Defaults you are accepting silently: --dataset.num_episodes=50, --dataset.episode_time_s=60, --dataset.reset_time_s=60. The dataset lands in ~/.cache/huggingface/lerobot/{repo-id}.

   bash

   lerobot-record \
     --robot.type=so100_follower \
     --robot.port=/dev/ttyACM0 \
     --robot.id=my_follower_arm \
     --robot.cameras="{ front: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
     --teleop.type=so100_leader \
     --teleop.port=/dev/ttyACM1 \
     --teleop.id=my_leader_arm \
     --dataset.repo_id=${HF_USER}/so100-cube-to-bowl \
     --dataset.num_episodes=50 \
     --dataset.single_task="Pick the yellow cube and put it in the bowl" \
     --dataset.push_to_hub=False \
     --display_data=true

3. 3
   Look at every episode before you publish

   Load it locally and read the metadata back. If total_episodes does not match what you think you recorded, stop here.

   bash

   lerobot-edit-dataset \
     --repo_id=${HF_USER}/so100-cube-to-bowl \
     --operation.type=info \
     --operation.show_features=true

4. 4
   Drop the bad episodes, then check what happened to the statistics

   delete_episodes writes a new dataset: it re-indexes episodes, rebuilds meta/episodes/, and re-aggregates meta/stats.json from the per-episode statistics of the episodes it kept. You do not need to recompute stats to get a consistent dataset. recompute_stats is the stronger, optional operation that rebuilds stats.json from scratch by iterating every frame - with the default output trap described below.

   bash

   lerobot-edit-dataset \
     --repo_id=${HF_USER}/so100-cube-to-bowl \
     --operation.type=delete_episodes \
     --operation.episode_indices "[7, 23, 41]" \
     --new_repo_id=${HF_USER}/so100-cube-to-bowl-clean
   
   # optional, and note the two flags: without them this writes a THIRD dataset
   lerobot-edit-dataset \
     --repo_id=${HF_USER}/so100-cube-to-bowl-clean \
     --new_repo_id=${HF_USER}/so100-cube-to-bowl-clean \
     --operation.type=recompute_stats \
     --operation.overwrite true

5. 5
   Push with the card fields filled in

   This is the step that turns an upload into a publication. push_to_hub() forwards unknown keyword arguments into the card template, so dataset_description, url, paper and citation_bibtex all land in the README instead of staying as [More Information Needed].

   python

   from lerobot.datasets import LeRobotDataset
   
   ds = LeRobotDataset("my-user/so100-cube-to-bowl-clean")
   
   ds.push_to_hub(
       tags=["so100", "pick-and-place", "teleoperation"],
       license="cc-by-4.0",          # default is "apache-2.0"
       private=False,
       push_videos=True,
       # everything below is forwarded into card_template.md
       dataset_description=(
           "47 teleoperated episodes of an SO-100 follower arm picking a 25 mm "
           "yellow cube from a 30x40 cm mat and dropping it into a white bowl. "
           "Two cameras at 640x480/30 fps: a fixed front view and a wrist view."
       ),
       url="https://github.com/<your-name>/so100-cube-to-bowl",
       citation_bibtex=(
           "@misc{so100cube2026,\n"
           "  title  = {SO-100 cube-to-bowl teleoperation dataset},\n"
           "  author = {Your Name},\n"
           "  year   = {2026},\n"
           "  url    = {https://huggingface.co/datasets/<your-name>/so100-cube-to-bowl-clean}\n"
           "}"
       ),
   )

The dataset card

The Hub renders README.md as the dataset card. It has two halves that do completely different jobs: a YAML front matter block the Hub parses for filtering, licence display and viewer configuration, and everything below it, which only humans read. LeRobot generates both from src/lerobot/datasets/card_template.md, and the generated prose half is close to empty.

The YAML block

What lerobot writes for you is: tags: [LeRobot] plus anything you passed, task_categories: [robotics], a configs entry pointing the viewer at data/*/*.parquet, and the licence. Everything else is yours to add. This is the block that makes your dataset findable, so it is worth ten minutes.

---
license: cc-by-4.0
pretty_name: SO-100 cube-to-bowl (47 episodes, 2 cameras)
task_categories:
  - robotics
size_categories:
  - 10K<n<100K
language:
  - en
tags:
  - LeRobot
  - so100
  - so101
  - pick-and-place
  - teleoperation
  - imitation-learning
  - video
configs:
  - config_name: default
    data_files: data/*/*.parquet
---

The half that decides whether anyone can reproduce you

The prose half of card_template.md has six substitution points, and only two get filled for you: license from the push_to_hub argument, and dataset_structure with a JSON dump of info.json. The other four are yours. dataset_description defaults to an empty string; url (rendered as Homepage), paper and citation_bibtex each default to the literal text [More Information Needed]. That triple is the signature of an unedited card, and you can see it on a large share of public LeRobot datasets. Fill them through push_to_hub, then add the sections below by editing README.md directly. Nothing enforces any of it, which is precisely why it does not happen.

• Hardware. Arm and variant (SO-100, SO-101, Koch v1.1, LeKiwi), servo model, supply voltage, and whether the leader and follower are the same model. A policy trained on your data will be deployed on hardware with different backlash. The SO-100 setup guide lists the variables that differ between two nominally identical builds.
• Cameras. One line per camera: key name, physical placement, resolution, fps, and lens. "observation.images.front, tripod 45 cm in front of the mat, 640x480, 30 fps" beats any photo.
• Calibration. Whether the arms were freshly calibrated and against which reference pose. Joint values from an uncalibrated arm are not comparable to yours.
• The task string, verbatim. It is embedded in the data and language-conditioned policies read it. LeRobot's own guidance is 25 to 50 characters and no names like task1 or demo2.
• Scene and variation. Object, its size, the surface, lighting, how many distinct start positions, how many episodes per position. This is what tells a reader whether your 50 episodes cover one pose or ten.
• What you removed. Episode indices deleted, and why. If you deleted 3 of 50, say 47 everywhere and say where the other 3 went.
• Known defects. The camera that dropped frames in episodes 12 to 15. The gripper that stuck. Nobody will hold this against you; discovering it after a training run, they will.
• A version tag you control, plus the date, so a citation resolves to fixed bytes.

If that list feels arbitrary, it is a compressed robot-specific version of the datasheet proposed in Datasheets for Datasets by Gebru and colleagues (arXiv 1803.09010, first posted 23 March 2018, revised through December 2021), which organises dataset documentation into motivation, composition, collection process, preprocessing, uses, distribution and maintenance. The robotics-specific part is that composition includes physical geometry: where the camera was, is part of the data.

Choosing a licence, and what it does not cover

Hugging Face requires a licence identifier from a fixed list before it will display one on the page. lerobot picks apache-2.0 unless you say otherwise, which is a software licence being applied to a video dataset. It works in practice, and it is not what most data publishers actually intend.

Two ways to get a dataset published

Make it trainable, not just downloadable

A dataset that loads is not a dataset that trains. The five policies you are most likely to point at it disagree about which format version they accept and how many episodes they need before fine-tuning produces anything. ACT trains from scratch by imitation learning and SmolVLA needs the fewest episodes of the five. Say in the card which one you built for.

That first column is the trap. GR00T N1.7 will not read a v3.0 dataset at all, and NVIDIA says so plainly: GR00T uses a flavour of the LeRobot v2 format because upstream datasets like DROID and LIBERO are published in v2. Publishing v3.0 is correct and current; it also means every GR00T user has to convert first. Publishing both, as two repos or two branches, is the friendly move, and the GR00T N1.7 on SO-100 guide assumes you have done it.

# v2.1 -> v3.0, run from a lerobot checkout against a dataset on the Hub.
# This one converts, pushes to main and moves the v3.0 tag for you.
python src/lerobot/scripts/convert_dataset_v21_to_v30.py \
  --repo-id=my-user/so100-cube-to-bowl

# convert a local copy instead, without touching the Hub
python src/lerobot/scripts/convert_dataset_v21_to_v30.py \
  --repo-id=my-user/so100-cube-to-bowl \
  --root=/path/to/local/dataset \
  --push-to-hub=false

# v3.0 -> v2, from the Isaac-GR00T repo, in its own venv
cd scripts/lerobot_conversion
uv venv && source .venv/bin/activate
uv pip install -e . --verbose
python convert_v3_to_v2.py --repo-id my-user/so100-cube-to-bowl

The check before you make it public

Hugging Face publishes conditions for hosting a large dataset, and the list starts with the card. They require a dataset card, require that you are sharing for community reuse rather than as private backup, require you to stay inside the repository limits, and ask for formats the ecosystem reads, naming Parquet and WebDataset. A LeRobot v3.0 repo meets the format condition through its Parquet shards, with the camera streams alongside as MP4. The limits that matter for robot data: fewer than 100k files per repo, fewer than 10k entries per folder, files under 200 GB. v3.0 sharding keeps you inside all three; v2.1, with one parquet and one mp4 per episode per camera, does not once you pass a few thousand episodes. The CLI and MCP server expose the same dataset operations if you would rather script this check.

1. Open meta/info.json and read total_episodes, total_frames, fps and robot_type out loud. Do they match the card?
2. Load the dataset fresh in a clean environment: LeRobotDataset("my-user/name"). If it needed a local cache to work, it is broken.
3. Open the dataset in the visualize_dataset Space and scrub through at least the first, middle and last episode.
4. Check the Data Studio viewer renders on the Hub page. If it does not, your configs YAML entry is wrong.
5. Scan every camera view for faces, screens, documents and windows.
6. Confirm the licence identifier in the YAML matches what you actually intend, not the apache-2.0 default.
7. Create your own dated git tag and reference it in the card.
8. Have somebody who was not in the room read the card and tell you what they still cannot determine.

One honest limit on all of this: a well-documented dataset does not make a policy work. The dataset card is upstream of the parts that break. A vision-language-action model fine-tuned on 50 clean episodes still fails when the camera moves 5 cm, and inference latency between 20 and 485 ms per action step decides whether the policy runs smoothly on the arm regardless of how good the data was. Publishing well is a courtesy to the next person, and a debugging aid for yourself. It is not a performance improvement.

Is the extra afternoon worth it

Questions people actually ask