GR00T N1.5 to N1.7: What Changed and How to Migrate

NVIDIA shipped GR00T N1.5 on 11 June 2025, then N1.6, and GR00T N1.7 is now the General Availability release on the main branch of the Isaac-GR00T repository. The version numbers suggest a point upgrade. They are misleading. The vision-language backbone was replaced, the action space went from absolute to relative, state and action dimensions grew from 64 and 32 to 132, and the fine-tuning entry point moved to a different file with different flags.

This is a migration guide, not a launch post. It covers what changed, whether your LeRobot dataset survives the move, whether an old checkpoint still loads (it does not), which flags were renamed, and when staying on N1.5 is correct. Every number below was read from a config file, a source file or a README on 2026-08-23, and where upstream contradicts itself that is said plainly.

Two different models that share a family name

The fastest way to see how far apart they are is to read the config.json files side by side. Each is public, and each is what the loader parses. Here is what they declare as of 2026-08-23, with N1.6 in the middle.

The parameter count is unchanged at roughly 3 billion in all three, which is why the headline stayed the same and the internals did not. Note the transformers pin: N1.5 and N1.6 record 4.51.3, N1.7 records 4.57.1. One environment cannot serve both, which matters more day to day than any architectural bullet.

# Read the declarations yourself, no clone and no GPU needed
curl -s https://huggingface.co/nvidia/GR00T-N1.5-3B/raw/main/config.json \
  | python3 -c "import json,sys; c=json.load(sys.stdin); h=c['action_head_cfg']; \
print(c['model_type'], 'horizon', c['action_horizon'], 'state', h['max_state_dim'])"

curl -s https://huggingface.co/nvidia/GR00T-N1.7-3B/raw/main/config.json \
  | python3 -c "import json,sys; c=json.load(sys.stdin); \
print(c['model_type'], 'horizon', c['action_horizon'], 'state', c['max_state_dim'])"

The backbone swap has the widest blast radius

N1.5 used a vendored Eagle vision-language model, frozen during both pretraining and fine-tuning. N1.6 switched to nvidia/Eagle-Block2A-2B-v2 and unfroze the top four LLM layers. N1.7 replaces Eagle entirely with nvidia/Cosmos-Reason2-2B, a 2.44 billion parameter VLM whose Hugging Face metadata lists Qwen/Qwen3-VL-2B-Instruct as its base model, and sets tune_top_llm_layers back to 0. The stated gain is flexible resolution: images are encoded in their native aspect ratio without padding.

There is a quieter consequence. A vision-language-action model inherits its language grounding from the backbone, so prompts tuned against Eagle can land differently after the swap, especially for tasks that name objects. If your policy carried an odd prompt that happened to work, re-test it.

The action head, the horizon, and relative actions

N1.7 keeps the flow-matching diffusion transformer head, so the architecture from the GR00T N1 paper still describes it: a vision-language module reads the scene and a diffusion transformer denoises an action chunk. What changed is the chunk, and what the numbers inside it mean.

The relative action space is NVIDIA's stated reason for N1.7's cross-embodiment behaviour: a delta means the same thing on a human arm and a robot arm, so priors from human video transfer. It is also the change most likely to break a naive port. Copy an N1.5 modality config forward and you feed absolute targets to a model expecting deltas, which reads as a calibration fault rather than a config fault. The N1.7 SO-100 example sets ActionRepresentation.RELATIVE for the arm joints and ActionRepresentation.ABSOLUTE for the gripper, since a binary open and close works better as a target.

Do your old N1.5 checkpoints still load? No.

This is usually the first question and the answer is unambiguous. The N1.5 model class lived in a flat module, gr00t/model/gr00t_n1.py, holding the class GR00T_N1_5. That file is gone from main, and so is scripts/gr00t_finetune.py. The packaged layout arrived with N1.6: the n1d6 branch holds a gr00t_n1d6 package, main holds gr00t_n1d7, and there is no gr00t_n1d5 package and never was. LeRobot went further and removed N1.5 support outright rather than letting it fail obscurely.

GR00T N1.5 support was removed from LeRobot. To keep using an N1.5
checkpoint, pin the last release that supports it:
`pip install 'lerobot==0.5.1'`. To use the current release, migrate to
GR00T N1.7 (model_version='n1.7', base model nvidia/GR00T-N1.7-3B).

The code comment there is unusually honest: the legacy identifier is retained so the N1.7 loader can fail loudly rather than silently treating an N1.5 checkpoint as N1.7. Mirror that in your own tooling: a silent mis-load produces a policy that runs, emits actions, and is wrong.

Dataset compatibility: episodes survive, config does not

The good news dominates. Both versions consume a GR00T flavour of the LeRobot v2 format: parquet under data/chunk-000/, mp4 under videos/chunk-000/, and a GR00T-specific meta/modality.json mapping the concatenated state and action arrays into named fields. That schema did not change, so a dataset recorded a year ago for an SO-100 is still valid input.

What changed is the layer above. N1.5 selected a registered Python class by name with --data-config so100, and that class carried its transforms inline: crop scale 0.95, resize to 224x224, color jitter, min_max normalization. N1.7 replaced it with --modality-config-path, a Python file you supply that builds ModalityConfig objects and calls register_modality_config. The transforms moved onto the CLI as --color-jitter-params, --shortest-image-edge, --crop-fraction and --use-percentiles.

1. 1
   Confirm the dataset version first

   GR00T reads LeRobot v2. A v3.0 dataset will not load, and the downstream failure is not obvious.

   bash

   python3 -c "import json;print(json.load(open('my_dataset/meta/info.json'))['codebase_version'])"
   # expect: v2.0 or v2.1

2. 2
   Convert down from v3 if needed

   The repo ships a helper with its own pyproject.toml, installed separately so its LeRobot pin does not fight the GR00T one.

   bash

   cd scripts/lerobot_conversion
   uv venv && source .venv/bin/activate
   uv pip install -e . --verbose
   python convert_v3_to_v2.py --repo-id <DATASET_REPO_ID>

3. 3
   Put modality.json back where the loader expects it

   Conversion does not produce the GR00T-specific mapping file. The SO-100 example maps single_arm to indices 0 to 5 and gripper to 5 to 6, for both state and action, with video keys front and wrist.

   bash

   cp examples/SO100/modality.json \
     my_dataset/meta/modality.json

4. 4
   Rewrite the data config as a modality config

   The real porting work: rebuild the old class as a file registering ModalityConfig objects under EmbodimentTag.NEW_EMBODIMENT, action representation set explicitly per key.

   python

   from gr00t.configs.data.embodiment_configs import register_modality_config
   from gr00t.data.embodiment_tags import EmbodimentTag
   from gr00t.data.types import (
       ActionConfig, ActionFormat, ActionRepresentation,
       ActionType, ModalityConfig,
   )
   
   so100_config = {
       "video": ModalityConfig(delta_indices=[0],
                               modality_keys=["front", "wrist"]),
       "state": ModalityConfig(delta_indices=[0],
                               modality_keys=["single_arm", "gripper"]),
       "action": ModalityConfig(
           delta_indices=list(range(0, 16)),
           modality_keys=["single_arm", "gripper"],
           action_configs=[
               ActionConfig(rep=ActionRepresentation.RELATIVE,
                            type=ActionType.NON_EEF,
                            format=ActionFormat.DEFAULT),
               ActionConfig(rep=ActionRepresentation.ABSOLUTE,
                            type=ActionType.NON_EEF,
                            format=ActionFormat.DEFAULT),
           ],
       ),
       "language": ModalityConfig(
           delta_indices=[0],
           modality_keys=["annotation.human.task_description"]),
   }
   
   register_modality_config(so100_config,
                            embodiment_tag=EmbodimentTag.NEW_EMBODIMENT)

The CLI is a different program now

Both entry points are tyro CLIs generated from a dataclass, so --help is authoritative. Here is the mapping between the flags you had and the flags you need.

# GR00T N1.5, the way it was (n1d5 branch)
python scripts/gr00t_finetune.py \
    --dataset-path ./my_dataset \
    --data-config so100 \
    --embodiment-tag new_embodiment \
    --batch-size 32 \
    --max-steps 20000 \
    --num-gpus 1

# GR00T N1.7, the way it is (main branch)
CUDA_VISIBLE_DEVICES=0 uv run python \
    gr00t/experiment/launch_finetune.py \
    --base-model-path nvidia/GR00T-N1.7-3B \
    --dataset-path ./my_dataset \
    --embodiment-tag NEW_EMBODIMENT \
    --modality-config-path examples/SO100/so100_config.py \
    --num-gpus 1 \
    --output-dir /tmp/so100_finetune \
    --max-steps 20000 \
    --global-batch-size 32 \
    --dataloader-num-workers 4

Does the new model actually do better?

The most comparable public evidence is LIBERO, because both branches publish a table for it: examples/Libero/README.md on n1d5 and examples/LIBERO/README.md on main.

For the wider picture, the arena tracks 85 VLA models with 332 benchmark results, each linked to its paper or model card, with separate entries for GR00T N1.5, GR00T N1.6 and GR00T N1.7.

Licensing: the quiet reason most teams move

This gets less attention than the backbone swap and decides more migrations. The N1.5 card says the model is "ready for non-commercial use" and links the NVIDIA OneWay Noncommercial License. The N1.7 card says "ready for commercial/non-commercial use" and links the NVIDIA Open Model License, with repo code under Apache 2.0. If you built a product on an N1.5 fine-tune, that driver does not care whether N1.7 is better on your task.

When staying on N1.5 is correct

Migration is not free, and a working N1.5 policy on a fixed task beats an untested N1.7 one. Stay put if any of these describe you.

• You have a deployed policy hitting its target on one arm, one cell, one task, and nothing is changing. A frozen branch is a stable branch.
• Your use is academic or internal, so the noncommercial license was never a constraint.
• Your hardware tops out at 24 GB and you relied on LoRA. Plan a hardware step, or look at SmolVLA and ACT, which run on any 24 GB card.
• You cannot accept a gated dependency in an air-gapped or tightly reviewed build. Cosmos-Reason2-2B is not optional for N1.7.
• You are mid-experiment. Changing the base model invalidates every baseline you recorded; finish, then migrate.
• Your task is fast and reactive rather than slow pick-and-place. Neither version fixes that, and 13 ms will not either.

One thing that is not a reason to stay: fear that your recorded episodes are wasted. The format is the part that survived intact, and a well-recorded dataset outlives every model generation you train on it. The data-collection guide covers what makes one durable.

Two ways to run the migration

Latency and cost after the move

N1.7 is marginally faster per action step than N1.5 here, 152 ms against 165 ms, on the same GPU tier. That is real but small, and it does not change the class of task either model can do. The inference latency constraint is unchanged: the policy has to sit next to the servos for anything fast. Across the five trainable models the control loop runs from 20 ms to 485 ms per step, and public-internet round trips on top of a 152 ms loop turn a working policy into a hesitant one. Remote inference suits slow pick-and-place, not fast reactive motion.

Inference pods carry an idle watchdog and destroy themselves after an idle period, so a forgotten migration test does not keep billing. Full numbers are on the pricing page, and the training docs record what the form sends to the trainer.

The migration checklist

1. Record the N1.5 baseline first: success rate on your task, over enough trials to mean something. Without it the migration has no verdict.
2. Check meta/info.json for codebase_version v2.0 or v2.1, and convert down from v3 if needed.
3. Rewrite the data config as a modality config file: RELATIVE for the arm axes, ABSOLUTE for the gripper.
4. Request access to nvidia/Cosmos-Reason2-2B and authenticate everywhere, including CI.
5. Run the shipped demo_data/cube_to_bowl_5 fine-tune end to end before touching your own data.
6. Retrain from nvidia/GR00T-N1.7-3B on the same dataset and episode count, with --use-percentiles set explicitly on both sides.
7. Compare on the arm, not on a benchmark, over enough trials to clear the 5 to 6 percent run-to-run variance. Then decommission n1d5.

If the retrained policy converges but the arm does nothing useful, that is a mapped failure rather than a migration problem. Loss falls, policy does nothing and policy only works in one setup are the two you will hit most. The CLI exposes the same operations if you would rather script the A/B than click it.

GR00T N1.5 to N1.7 is a backbone swap plus an action-space change, both moves the wider VLA field has been making. Pi0's flow-matching design reached a similar action head from another direction, and the wider VLA overview puts the family in order. If this migration is your entry point, start from the SO-100 setup guide.