Hydra Configuration System

Hydra Configuration System#

Isaac Lab supports the Hydra configuration system to modify the task’s configuration using command line arguments, which can be useful to automate experiments and perform hyperparameter tuning.

Any parameter of the environment can be modified by adding one or multiple elements of the form env.a.b.param1=value to the command line input, where a.b.param1 reflects the parameter’s hierarchy, for example env.actions.joint_effort.scale=10.0. Similarly, the agent’s parameters can be modified by using the agent prefix, for example agent.seed=2024.

The way these command line arguments are set follow the exact structure of the configuration files. Since the different RL frameworks use different conventions, there might be differences in the way the parameters are set. For example, with rl_games the seed will be set with agent.params.seed, while with rsl_rl, skrl and sb3 it will be set with agent.seed.

As a result, training with hydra arguments can be run with the following syntax:

python scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Cartpole-v0 --headless env.actions.joint_effort.scale=10.0 agent.seed=2024

python scripts/reinforcement_learning/rl_games/train.py --task=Isaac-Cartpole-v0 --headless env.actions.joint_effort.scale=10.0 agent.params.seed=2024

python scripts/reinforcement_learning/skrl/train.py --task=Isaac-Cartpole-v0 --headless env.actions.joint_effort.scale=10.0 agent.seed=2024

python scripts/reinforcement_learning/sb3/train.py --task=Isaac-Cartpole-v0 --headless env.actions.joint_effort.scale=10.0 agent.seed=2024

The above command will run the training script with the task Isaac-Cartpole-v0 in headless mode, and set the env.actions.joint_effort.scale parameter to 10.0 and the agent.seed parameter to 2024.

Note

To keep backwards compatibility, and to provide a more user-friendly experience, we have kept the old cli arguments of the form --param, for example --num_envs, --seed, --max_iterations. These arguments have precedence over the hydra arguments, and will overwrite the values set by the hydra arguments.

Modifying advanced parameters#

Callables#

It is possible to modify functions and classes in the configuration files by using the syntax module:attribute_name. For example, in the Cartpole environment:

class ObservationsCfg:
    """Observation specifications for the MDP."""

    @configclass
    class PolicyCfg(ObsGroup):
        """Observations for policy group."""

        # observation terms (order preserved)
        joint_pos_rel = ObsTerm(func=mdp.joint_pos_rel)
        joint_vel_rel = ObsTerm(func=mdp.joint_vel_rel)

        def __post_init__(self) -> None:
            self.enable_corruption = False
            self.concatenate_terms = True

    # observation groups
    policy: PolicyCfg = PolicyCfg()

we could modify joint_pos_rel to compute absolute positions instead of relative positions with env.observations.policy.joint_pos_rel.func=isaaclab.envs.mdp:joint_pos.

Setting parameters to None#

To set parameters to None, use the null keyword, which is a special keyword in Hydra that is automatically converted to None. In the above example, we could also disable the joint_pos_rel observation by setting it to None with env.observations.policy.joint_pos_rel=null.

Dictionaries#

Elements in dictionaries are handled as a parameters in the hierarchy. For example, in the Cartpole environment:



@configclass
class ObservationsCfg:
    """Observation specifications for the MDP."""

    @configclass
    class PolicyCfg(ObsGroup):
        """Observations for policy group."""

        # observation terms (order preserved)
        joint_pos_rel = ObsTerm(func=mdp.joint_pos_rel)
        joint_vel_rel = ObsTerm(func=mdp.joint_vel_rel)

        def __post_init__(self) -> None:
            self.enable_corruption = False
            self.concatenate_terms = True

    # observation groups
    policy: PolicyCfg = PolicyCfg()


@configclass
class EventCfg:
    """Configuration for events."""

the position_range parameter can be modified with env.events.reset_cart_position.params.position_range="[-2.0, 2.0]". This example shows two noteworthy points:

  • The parameter we set has a space, so it must be enclosed in quotes.

  • The parameter is a list while it is a tuple in the config. This is due to the fact that Hydra does not support tuples.

Modifying inter-dependent parameters#

Particular care should be taken when modifying the parameters using command line arguments. Some of the configurations perform intermediate computations based on other parameters. These computations will not be updated when the parameters are modified.

For example, for the configuration of the Cartpole camera depth environment:

class CartpoleDepthCameraEnvCfg(CartpoleRGBCameraEnvCfg):
    # camera
    tiled_camera: TiledCameraCfg = TiledCameraCfg(
        prim_path="/World/envs/env_.*/Camera",
        offset=TiledCameraCfg.OffsetCfg(pos=(-5.0, 0.0, 2.0), rot=(0.0, 0.0, 0.0, 1.0), convention="world"),
        data_types=["depth"],
        spawn=sim_utils.PinholeCameraCfg(
            focal_length=24.0, focus_distance=400.0, horizontal_aperture=20.955, clipping_range=(0.1, 20.0)
        ),
        width=100,
        height=100,
    )

    # spaces
    observation_space = [tiled_camera.height, tiled_camera.width, 1]

If the user were to modify the width of the camera, i.e. env.tiled_camera.width=128, then the parameter env.observation_space=[80,128,1] must be updated and given as input as well.

Similarly, the __post_init__ method is not updated with the command line inputs. In the LocomotionVelocityRoughEnvCfg, for example, the post init update is as follows:

class LocomotionVelocityRoughEnvCfg(ManagerBasedRLEnvCfg):
    """Configuration for the locomotion velocity-tracking environment."""

    # Scene settings
    scene: MySceneCfg = MySceneCfg(num_envs=4096, env_spacing=2.5)
    # Basic settings
    observations: ObservationsCfg = ObservationsCfg()
    actions: ActionsCfg = ActionsCfg()
    commands: CommandsCfg = CommandsCfg()
    # MDP settings
    rewards: RewardsCfg = RewardsCfg()
    terminations: TerminationsCfg = TerminationsCfg()
    events: EventsCfg = MISSING
    curriculum: CurriculumCfg = CurriculumCfg()

    def __post_init__(self):
        """Post initialization."""
        # general settings
        self.decimation = 4
        self.episode_length_s = 20.0
        # simulation settings
        self.sim.dt = 0.005
        self.sim.render_interval = self.decimation
        self.sim.physics_material = self.scene.terrain.physics_material
        # update sensor update periods
        # we tick all the sensors based on the smallest update period (physics update period)
        if self.scene.height_scanner is not None:
            self.scene.height_scanner.update_period = self.decimation * self.sim.dt
        if self.scene.contact_forces is not None:
            self.scene.contact_forces.update_period = self.sim.dt

        # check if terrain levels curriculum is enabled - if so, enable curriculum for terrain generator
        # this generates terrains with increasing difficulty and is useful for training
        if getattr(self.curriculum, "terrain_levels", None) is not None:
            if self.scene.terrain.terrain_generator is not None:
                self.scene.terrain.terrain_generator.curriculum = True
        else:
            if self.scene.terrain.terrain_generator is not None:
                self.scene.terrain.terrain_generator.curriculum = False

Here, when modifying env.decimation or env.sim.dt, the user needs to give the updated env.sim.render_interval, env.scene.height_scanner.update_period, and env.scene.contact_forces.update_period as input as well.

Custom Configuration Validation#

Configclass objects can define a validate_config() method to perform domain-specific validation after all fields have been resolved. This hook is called automatically after preset resolution and MISSING-field checks succeed, allowing you to catch invalid parameter combinations early with clear error messages.

Defining a validation hook:

from isaaclab.utils import configclass

@configclass
class MyEnvCfg:
    physics_backend: str = "physx"
    use_multi_asset: bool = False

    def validate_config(self):
        if self.physics_backend == "newton" and self.use_multi_asset:
            raise ValueError(
                "Newton physics does not support multi-asset spawning."
                " Use a single-geometry object preset instead."
            )

When it runs:

  1. All MISSING fields are checked first — if any remain, TypeError is raised.

  2. Only then is validate_config() called on the top-level config object.

  3. The hook should raise ValueError with a clear message and migration guidance.

Common validation patterns:

  • Physics backend compatibility (e.g., Newton does not support multi-asset spawning)

  • Renderer and camera data type compatibility (e.g., Newton Warp only supports rgb and depth)

  • Feature extractor compatibility with camera configuration

Preset System#

The preset system lets you swap out entire config sections – or individual scalar values – with a single command line argument. Instead of overriding individual fields, you select a named preset that completely replaces the config section (no field merging).

Presets are declared by subclassing PresetCfg or by using the preset() convenience factory. The system recursively discovers all presets from nested configs automatically, including presets inside dict-valued fields (e.g. actuators).

Override Order#

Overrides are applied in sequence:

  1. Auto-default: Configs with a "default" field auto-apply without CLI args

  2. Global presets: presets=newton,inference applies to ALL matching configs

  3. Path presets: env.backend=newton replaces a specific section

  4. Scalar overrides: env.sim.dt=0.001 modifies individual fields

Defining Presets with PresetCfg#

Create a PresetCfg subclass where each field is a named alternative. The default field is the config used when no CLI override is given:

from isaaclab_tasks.utils import PresetCfg

@configclass
class PhysicsCfg(PresetCfg):
    default: PhysxCfg = PhysxCfg()
    newton: NewtonCfg = NewtonCfg()

@configclass
class MyEnvCfg:
    physics: PhysicsCfg = PhysicsCfg()

# Use Newton physics backend
python train.py --task=Isaac-Reach-Franka-v0 env.physics=newton

The default field can be set to None to make an optional feature that is disabled unless explicitly selected:

@configclass
class CameraPresetCfg(PresetCfg):
    default = None
    small: CameraCfg = CameraCfg(width=64, height=64)
    large: CameraCfg = CameraCfg(width=256, height=256)

@configclass
class SceneCfg:
    camera: CameraPresetCfg = CameraPresetCfg()

# camera is None -- no camera overhead
python train.py --task=Isaac-Reach-Franka-v0

# activate camera with the "large" preset
python train.py --task=Isaac-Reach-Franka-v0 env.scene.camera=large

Inline Presets with preset()#

For simple values (scalars, lists) that don’t warrant a full subclass, use the preset() factory. It dynamically creates a PresetCfg instance from keyword arguments:

from isaaclab_tasks.utils.hydra import preset

# Scalar preset -- one line, no boilerplate class
self.scene.robot.actuators["legs"].armature = preset(default=0.0, newton=0.01, physx=0.0)

This is equivalent to defining a PresetCfg subclass with three float fields, but without the ceremony. The default keyword is required.

preset() works for any value type – scalars, lists, or even config instances:

# Resolution preset on a camera config field
width = preset(default=64, res128=128, res256=256)

# List preset for camera data types
@configclass
class DataTypeCfg(PresetCfg):
    default: list = ["rgb"]
    depth: list = ["depth"]
    albedo: list = ["albedo"]

Use preset() when the definition fits on a single line. Use a PresetCfg subclass when the options are verbose enough to benefit from type annotations and multiline formatting.

The preset system discovers preset() values anywhere in the config tree, including inside dict-valued fields such as actuators:

# Select newton preset globally -- sets armature to 0.01
python train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 presets=newton

Using Presets#

Path presets – select a specific preset for one config path:

python train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 \
    env.events=newton

Global presets – apply the same preset name everywhere it exists:

# Apply "newton" preset to all configs that define it
python train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 \
    presets=newton

Multiple global presets – apply several non-conflicting presets:

python train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 \
    presets=newton,inference

Combined – global presets + scalar overrides:

python train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 \
    presets=newton \
    env.sim.dt=0.002

Global Preset Conflict Detection#

If two global presets both match the same config path, an error is raised so the ambiguity is caught early:

ValueError: Conflicting global presets: 'foo' and 'bar'
            both define preset for 'env.events'

Real-World Example#

The ANYmal-C locomotion environment shows both PresetCfg and preset() working together:

@configclass
class AnymalCPhysxEventsCfg(EventsCfg, StartupEventsCfg):
    pass


@configclass
class AnymalCEventsCfg(PresetCfg):
    default = AnymalCPhysxEventsCfg()
    newton = EventsCfg()
    physx = default


@configclass
class AnymalCRoughEnvCfg(LocomotionVelocityRoughEnvCfg):
    events: AnymalCEventsCfg = AnymalCEventsCfg()

    def __post_init__(self):
        # post init of parent
        super().__post_init__()
        # switch robot to anymal-c
        self.scene.robot = ANYMAL_C_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot")
        self.scene.robot.actuators["legs"].armature = preset(default=0.0, newton=0.01, physx=0.0)

A single presets=newton on the command line resolves every PresetCfg and preset() that defines a newton field: the physics engine is swapped to Newton, AnymalCEventsCfg selects Newton-compatible events, and the actuator armature is set to 0.01.

# Default (PhysX events, armature=0.0)
python train.py --task=Isaac-Velocity-Rough-Anymal-C-v0

# Newton (Newton events, armature=0.01)
python train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 presets=newton

Summary#

Override Type

Syntax

Effect

Scalar

env.sim.dt=0.001

Modify single field

Path preset

env.events=newton

Replace entire section

Global preset

presets=newton

Apply everywhere matching

Combined

presets=newton env.sim.dt=0.001

Global + scalar overrides