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,
)
src/lerobot/configs/train.py
Policy configuration (ACTConfig, DiffusionConfig, etc.).
Number of training steps.
Learning rate scheduler configuration.
Weights & Biases logging configuration.
Evaluation frequency in steps.
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),
)
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",
)
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()
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
lerobot-train --config config.yaml
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).
GPU devices to use (e.g., 0,1,2,3).
Weights & Biases API key.
Hugging Face API token for private datasets/models.
Configuration Best Practices
- Use YAML for Experiments: Store configs in version control
- Type Safety: Leverage dataclass type checking
- Defaults: Provide sensible defaults
- Validation: Implement custom validation in
__post_init__
- 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