Backward compatibility

Policy Normalization Migration (PR #1452)

Breaking Change: LeRobot policies no longer have built-in normalization layers embedded in their weights. Normalization is now handled by external PolicyProcessorPipeline components.

What changed?

Impact on existing models

• Models trained before PR #1452 have normalization embedded in their weights
• These models need migration to work with the new PolicyProcessorPipeline system
• The migration extracts normalization statistics and creates separate processor pipelines

Migrating old models

Use the migration script to convert models with embedded normalization:

python src/lerobot/processor/migrate_policy_normalization.py \
    --pretrained-path lerobot/act_aloha_sim_transfer_cube_human \
    --push-to-hub \
    --branch migrated

The script:

1. Extracts normalization statistics from model weights
2. Creates external preprocessor and postprocessor pipelines
3. Removes normalization layers from model weights
4. Saves clean model + processor pipelines
5. Pushes to Hub with automatic PR creation

Using migrated models

# New usage pattern (after migration)
from lerobot.policies.factory import make_policy, make_pre_post_processors

# Load model and processors separately
policy = make_policy(config, ds_meta=dataset.meta)
preprocessor, postprocessor = make_pre_post_processors(
    policy_cfg=config,
    dataset_stats=dataset.meta.stats
)

# Process data through pipeline
processed_batch = preprocessor(raw_batch)
action = policy.select_action(processed_batch)
final_action = postprocessor(action)

Hardware API redesign

PR #777 improves the LeRobot calibration but is not backward-compatible. Below is a overview of what changed and how you can continue to work with datasets created before this pull request.

What changed?

Impact on existing datasets

• Recorded trajectories created before PR #777 will replay incorrectly if loaded directly:
  • Joint angles are offset and incorrectly normalized.
• Any models directly finetuned or trained on the old data will need their inputs and outputs converted.

Using datasets made with the previous calibration system

We provide a migration example script for replaying an episode recorded with the previous calibration here: examples/backward_compatibility/replay.py. Below we take you through the modifications that are done in the example script to make the previous calibration datasets work.

+   key = f"{name.removeprefix('main_')}.pos"
    action[key] = action_array[i].item()
+   action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90)
+   action["elbow_flex.pos"] -= 90

Let's break this down. New codebase uses .pos suffix for the position observations and we have removed main_ prefix:

key = f"{name.removeprefix('main_')}.pos"

For "shoulder_lift" (id = 2), the 0 position is changed by -90 degrees and the direction is reversed compared to old calibration/code.

action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90)

For "elbow_flex" (id = 3), the 0 position is changed by -90 degrees compared to old calibration/code.

action["elbow_flex.pos"] -= 90

To use degrees normalization we then set the --robot.use_degrees option to true.

python examples/backward_compatibility/replay.py \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem5A460814411 \
    --robot.id=blue \
+   --robot.use_degrees=true \
    --dataset.repo_id=my_dataset_id \
    --dataset.episode=0

Using policies trained with the previous calibration system

Policies output actions in the same format as the datasets (torch.Tensors). Therefore, the same transformations should be applied.

To find these transformations, we recommend to first try and and replay an episode of the dataset your policy was trained on using the section above. Then, add these same transformations on your inference script (shown here in the record.py script):

action_values = predict_action(
    observation_frame,
    policy,
    get_safe_torch_device(policy.config.device),
    policy.config.use_amp,
    task=single_task,
    robot_type=robot.robot_type,
    )
    action = {key: action_values[i].item() for i, key in enumerate(robot.action_features)}

+   action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90)
+   action["elbow_flex.pos"] -= 90
    robot.send_action(action)

If you have questions or run into migration issues, feel free to ask them on Discord