Configuration

Configuration utilities for robot learning pipelines

LeRobot uses dataclass-based configuration with the draccus library for type-safe, hierarchical configs.

Overview

Configuration in LeRobot:

• Type-safe dataclass configurations
• Command-line argument parsing
• YAML file support
• Hierarchical config composition
• Validation and defaults

Configuration Classes

TrainPipelineConfig

Main configuration for training pipelines.

from lerobot.configs.train import TrainPipelineConfig

config = TrainPipelineConfig(
    policy=ACTConfig(),
    dataset=DatasetConfig(repo_id="lerobot/pusht"),
    steps=100000,
    batch_size=32,
)

Location: src/lerobot/configs/train.py

policy · PolicyConfig · required

Policy configuration (ACTConfig, DiffusionConfig, etc.).

dataset · DatasetConfig · required

Dataset configuration.

steps · int · default: "100000"

Number of training steps.

batch_size · int · default: "32"

Batch size per device.

optimizer · OptimizerConfig

Optimizer configuration.

lr_scheduler · LRSchedulerConfig

Learning rate scheduler configuration.

wandb · WandBConfig

Weights & Biases logging configuration.

eval_freq · int · default: "10000"

Evaluation frequency in steps.

save_freq · int · default: "10000"

Checkpoint save frequency in steps.

EvalPipelineConfig

Configuration for evaluation pipelines.

from lerobot.configs.eval import EvalPipelineConfig

config = EvalPipelineConfig(
    policy=PreTrainedConfig(path="lerobot/diffusion_pusht"),
    env=EnvConfig(type="pusht"),
    eval=EvalConfig(n_episodes=50),
)

Location: src/lerobot/configs/eval.py

PolicyConfig

Base class for policy configurations.

from lerobot.policies import ACTConfig

config = ACTConfig(
    dim_model=256,
    n_heads=8,
    chunk_size=100,
    device="cuda",
)

All policy configs inherit from this base.

DatasetConfig

Dataset loading configuration.

from lerobot.configs.dataset import DatasetConfig

config = DatasetConfig(
    repo_id="lerobot/pusht",
    root="./datasets/pusht",
    episodes=[0, 1, 2, 3, 4],
    delta_timestamps={
        "observation.images.top": [-0.033, 0.0],
        "action": [0.0, 0.033, 0.066],
    },
)

OptimizerConfig

Optimizer configuration.

from lerobot.configs.optim import OptimizerConfig

config = OptimizerConfig(
    type="adamw",
    lr=1e-4,
    weight_decay=0.01,
    grad_clip_norm=10.0,
)

Command-Line Interface

LeRobot uses draccus for automatic CLI generation:

import draccus
from dataclasses import dataclass

@dataclass
class MyConfig:
    learning_rate: float = 1e-4
    batch_size: int = 32
    device: str = "cuda"

@draccus.wrap()
def main(cfg: MyConfig):
    print(f"Learning rate: {cfg.learning_rate}")
    print(f"Batch size: {cfg.batch_size}")

if __name__ == "__main__":
    main()

Run with:

python script.py --learning_rate=5e-5 --batch_size=64

YAML Configuration Files

Create reusable configuration files:

# config.yaml
policy:
  type: act
  dim_model: 256
  n_heads: 8
  chunk_size: 100

dataset:
  repo_id: lerobot/pusht
  delta_timestamps:
    observation.images.top:
      - -0.033
      - 0.0
    action:
      - 0.0
      - 0.033
      - 0.066

steps: 100000
batch_size: 32

optimizer:
  type: adamw
  lr: 0.0001
  weight_decay: 0.01

wandb:
  enable: true
  project: my_project
  entity: my_username

Load with:

lerobot-train --config config.yaml

Or override specific values:

lerobot-train --config config.yaml --batch_size=64 --optimizer.lr=5e-5

Programmatic Usage

Create Config Programmatically

from lerobot.configs.train import TrainPipelineConfig
from lerobot.policies import ACTConfig
from lerobot.configs.dataset import DatasetConfig
from lerobot.configs.optim import OptimizerConfig

config = TrainPipelineConfig(
    policy=ACTConfig(
        dim_model=256,
        n_heads=8,
    ),
    dataset=DatasetConfig(
        repo_id="lerobot/pusht",
    ),
    steps=100000,
    batch_size=32,
    optimizer=OptimizerConfig(
        lr=1e-4,
        weight_decay=0.01,
    ),
)

Load Config from YAML

import draccus
from lerobot.configs.train import TrainPipelineConfig
from pathlib import Path

with open("config.yaml") as f:
    config = draccus.load(TrainPipelineConfig, f)

print(config.policy.type)
print(config.batch_size)

Save Config to YAML

import draccus
from lerobot.configs.train import TrainPipelineConfig
from pathlib import Path

config = TrainPipelineConfig(
    # ... configuration ...
)

with open("config.yaml", "w") as f:
    draccus.dump(config, f)

Validate Config

from lerobot.configs.train import TrainPipelineConfig

config = TrainPipelineConfig(
    # ... configuration ...
)

# Validate (raises error if invalid)
config.validate()

Convert Config to Dict

from dataclasses import asdict
from lerobot.configs.train import TrainPipelineConfig

config = TrainPipelineConfig(
    # ... configuration ...
)

config_dict = asdict(config)
print(config_dict)

Environment Variables

LeRobot respects these environment variables:

HF_LEROBOT_HOME · str · default: "~/.cache/huggingface/lerobot"

Root directory for LeRobot data (datasets, calibrations).

CUDA_VISIBLE_DEVICES · str

GPU devices to use (e.g., 0,1,2,3).

WANDB_API_KEY · str

Weights & Biases API key.

HF_TOKEN · str

Hugging Face API token for private datasets/models.

Configuration Best Practices

1. Use YAML for Experiments: Store configs in version control
2. Type Safety: Leverage dataclass type checking
3. Defaults: Provide sensible defaults
4. Validation: Implement custom validation in __post_init__
5. Modularity: Compose configs from smaller pieces

Example Custom Config

from dataclasses import dataclass, field
from typing import Optional

@dataclass
class CustomRobotConfig:
    type: str
    port: str
    id: str
    calibration_dir: Optional[str] = None
    max_velocity: float = 1.0
    cameras: dict = field(default_factory=dict)
    
    def __post_init__(self):
        # Validation
        if self.max_velocity <= 0:
            raise ValueError("max_velocity must be positive")
        if not self.port.startswith("/dev/"):
            raise ValueError("port must start with /dev/")

# Usage
config = CustomRobotConfig(
    type="my_robot",
    port="/dev/ttyUSB0",
    id="robot_1",
    max_velocity=0.5,
    cameras={
        "front": {"type": "opencv", "index": 0},
    },
)

See Also

• lerobot-train - Training script configuration
• lerobot-eval - Evaluation script configuration
• Policy API - Policy configurations
• draccus Documentation - Configuration library