Fix optional ovphysx preset imports

Add a lazy optional preset helper so task configs can advertise optional backend presets without importing their packages during default config loading.

Use it for direct task OV-PhysX physics presets and keep locomotion gear selection independent of the optional package import.

Author: AntoineRichard

source/isaaclab_tasks/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "1.5.25"
+version = "1.5.26"
 
 # Description
 title = "Isaac Lab Environments"

source/isaaclab_tasks/docs/CHANGELOG.rst

@@ -1,6 +1,16 @@
 Changelog
 ---------
 
+1.5.26 (2026-04-28)
+~~~~~~~~~~~~~~~~~~~
+
+Fixed
+^^^^^
+
+* Fixed direct task physics presets to keep the OV-PhysX backend optional and avoid
+  importing ``isaaclab_ovphysx`` unless the ``ovphysx`` preset is selected.
+
+
 1.5.25 (2026-04-23)
 ~~~~~~~~~~~~~~~~~~~
 

source/isaaclab_tasks/isaaclab_tasks/direct/ant/ant_env_cfg.py

@@ -6,18 +6,19 @@
 from __future__ import annotations
 
 from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
-from isaaclab_ovphysx.physics import OvPhysxCfg
 from isaaclab_physx.physics import PhysxCfg
 
 import isaaclab.sim as sim_utils
 from isaaclab.assets import ArticulationCfg
 from isaaclab.envs import DirectRLEnvCfg
+from isaaclab.physics import PhysicsCfg
 from isaaclab.scene import InteractiveSceneCfg
 from isaaclab.sim import SimulationCfg
 from isaaclab.terrains import TerrainImporterCfg
 from isaaclab.utils import configclass
 
 from isaaclab_tasks.utils import PresetCfg
+from isaaclab_tasks.utils.physics_presets import ovphysx_preset
 
 from isaaclab_assets.robots.ant import ANT_CFG
 
@@ -37,7 +38,7 @@ class AntPhysicsCfg(PresetCfg):
         num_substeps=1,
         debug_mode=False,
     )
-    ovphysx: OvPhysxCfg = OvPhysxCfg()
+    ovphysx: PhysicsCfg = ovphysx_preset()
 
 
 @configclass

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_env_cfg.py

@@ -6,16 +6,17 @@
 from __future__ import annotations
 
 from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
-from isaaclab_ovphysx.physics import OvPhysxCfg
 from isaaclab_physx.physics import PhysxCfg
 
 from isaaclab.assets import ArticulationCfg
 from isaaclab.envs import DirectRLEnvCfg
+from isaaclab.physics import PhysicsCfg
 from isaaclab.scene import InteractiveSceneCfg
 from isaaclab.sim import SimulationCfg
 from isaaclab.utils import configclass
 
 from isaaclab_tasks.utils import PresetCfg
+from isaaclab_tasks.utils.physics_presets import ovphysx_preset
 
 from isaaclab_assets.robots.cartpole import CARTPOLE_CFG
 
@@ -36,7 +37,7 @@ class CartpolePhysicsCfg(PresetCfg):
         debug_mode=False,
         use_cuda_graph=True,
     )
-    ovphysx: OvPhysxCfg = OvPhysxCfg()
+    ovphysx: PhysicsCfg = ovphysx_preset()
 
 
 @configclass

source/isaaclab_tasks/isaaclab_tasks/direct/humanoid/humanoid_env_cfg.py

@@ -6,18 +6,19 @@
 from __future__ import annotations
 
 from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg
-from isaaclab_ovphysx.physics import OvPhysxCfg
 from isaaclab_physx.physics import PhysxCfg
 
 import isaaclab.sim as sim_utils
 from isaaclab.assets import ArticulationCfg
 from isaaclab.envs import DirectRLEnvCfg
+from isaaclab.physics import PhysicsCfg
 from isaaclab.scene import InteractiveSceneCfg
 from isaaclab.sim import SimulationCfg
 from isaaclab.terrains import TerrainImporterCfg
 from isaaclab.utils import configclass
 
 from isaaclab_tasks.utils import PresetCfg
+from isaaclab_tasks.utils.physics_presets import ovphysx_preset
 
 from isaaclab_assets import HUMANOID_CFG
 
@@ -38,7 +39,7 @@ class HumanoidPhysicsCfg(PresetCfg):
         num_substeps=2,
         debug_mode=False,
     )
-    ovphysx: OvPhysxCfg = OvPhysxCfg()
+    ovphysx: PhysicsCfg = ovphysx_preset()
 
 
 @configclass

source/isaaclab_tasks/isaaclab_tasks/direct/locomotion/locomotion_env.py

@@ -8,7 +8,6 @@
 import torch
 import warp as wp
 from isaaclab_newton.physics import NewtonCfg
-from isaaclab_ovphysx.physics import OvPhysxCfg
 from isaaclab_physx.physics import PhysxCfg
 
 import isaaclab.sim as sim_utils
@@ -80,7 +79,8 @@ def __init__(self, cfg: DirectRLEnvCfg, render_mode: str | None = None, **kwargs
         self.action_scale = self.cfg.action_scale
         # Resolve the joint gears based on the physics type, since they do not have the same joint ordering.
         if isinstance(self.cfg.joint_gears, dict):
-            if isinstance(self.cfg.sim.physics, (PhysxCfg, OvPhysxCfg)):
+            physics_type = type(self.cfg.sim.physics).__name__
+            if isinstance(self.cfg.sim.physics, PhysxCfg) or physics_type == "OvPhysxCfg":
                 joint_gears = self.cfg.joint_gears["physx"]
             elif isinstance(self.cfg.sim.physics, NewtonCfg):
                 joint_gears = self.cfg.joint_gears["newton"]

source/isaaclab_tasks/isaaclab_tasks/utils/__init__.pyi

@@ -9,6 +9,7 @@ __all__ = [
     "load_cfg_from_registry",
     "parse_env_cfg",
     "PresetCfg",
+    "optional_preset",
     "preset",
     "resolve_task_config",
     "hydra_task_config",
@@ -18,7 +19,7 @@ __all__ = [
     "compute_kit_requirements",
 ]
 
-from .hydra import PresetCfg, preset, hydra_task_config, resolve_task_config, resolve_presets
+from .hydra import PresetCfg, optional_preset, preset, hydra_task_config, resolve_task_config, resolve_presets
 from .importer import import_packages
 from .parse_cfg import get_checkpoint_path, load_cfg_from_registry, parse_env_cfg
 from .sim_launcher import add_launcher_args, launch_simulation, compute_kit_requirements

source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py

@@ -25,6 +25,7 @@
 """
 
 import functools
+import importlib
 import sys
 from collections.abc import Callable, Mapping
 
@@ -58,6 +59,90 @@ class PhysicsCfg(PresetCfg):
     pass
 
 
+class _OptionalPreset:
+    """Lazy preset alternative backed by an optional import."""
+
+    __slots__ = ("import_path", "install_hint", "kwargs", "preset_name")
+
+    def __init__(
+        self,
+        import_path: str,
+        preset_name: str,
+        install_hint: str | None = None,
+        kwargs: dict[str, object] | None = None,
+    ):
+        self.import_path = import_path
+        self.preset_name = preset_name
+        self.install_hint = install_hint
+        self.kwargs = kwargs or {}
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, _OptionalPreset)
+            and self.import_path == other.import_path
+            and self.preset_name == other.preset_name
+            and self.install_hint == other.install_hint
+            and self.kwargs == other.kwargs
+        )
+
+    def load(self) -> object:
+        module_name, _, attr_name = self.import_path.partition(":")
+        try:
+            module = importlib.import_module(module_name)
+            cfg_cls = getattr(module, attr_name)
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(self._format_error(exc)) from exc
+        except (AttributeError, ImportError) as exc:
+            raise ImportError(self._format_error(exc)) from exc
+        return cfg_cls(**self.kwargs)
+
+    def _format_error(self, exc: Exception) -> str:
+        message = (
+            f"Preset '{self.preset_name}' requires optional config '{self.import_path}', but it could not be imported."
+        )
+        if self.install_hint:
+            message += f" {self.install_hint}"
+        message += f" Original error: {exc}"
+        return message
+
+
+def optional_preset(
+    import_path: str,
+    *,
+    preset_name: str | None = None,
+    install_hint: str | None = None,
+    **kwargs: object,
+) -> _OptionalPreset:
+    """Create a lazy preset alternative for an optional package.
+
+    The target class is imported and instantiated only when the preset is selected.
+    This lets default task configs advertise optional presets without importing
+    optional packages during normal config loading.
+
+    Args:
+        import_path: Import path in ``"module:ClassName"`` form.
+        preset_name: User-facing preset name for error messages. Defaults to the
+            imported class name.
+        install_hint: Optional guidance appended to import errors.
+        **kwargs: Keyword arguments forwarded to the imported config class.
+
+    Returns:
+        A lazy preset alternative that can be used as a :class:`PresetCfg` field.
+
+    Raises:
+        ValueError: If :attr:`import_path` is not in ``"module:ClassName"`` form.
+    """
+    module_name, sep, attr_name = import_path.partition(":")
+    if not sep or not module_name or not attr_name:
+        raise ValueError(f"Optional preset import path must use 'module:ClassName' form, got: {import_path!r}.")
+    return _OptionalPreset(import_path, preset_name or attr_name, install_hint, kwargs)
+
+
+def _materialize_optional_preset(value) -> object:
+    """Instantiate an optional preset if needed."""
+    return value.load() if isinstance(value, _OptionalPreset) else value
+
+
 def preset(**options) -> PresetCfg:
     """Create a :class:`PresetCfg` instance from keyword arguments.
 
@@ -179,9 +264,9 @@ def _pick_alternative(preset_obj: PresetCfg, selected: set[str], path: str = "")
     fields = _preset_fields(preset_obj)
     for name in selected:
         if name in fields:
-            return fields[name]
+            return _materialize_optional_preset(fields[name])
     if "default" in fields:
-        return fields["default"]
+        return _materialize_optional_preset(fields["default"])
     raise ValueError(
         f"PresetCfg {type(preset_obj).__name__} at '{path}' has no 'default' field "
         f"and none of the selected presets {selected} match its fields {set(fields.keys())}."
@@ -522,7 +607,7 @@ def _path_reachable(sec: str, path: str) -> bool:
     for full_path in sorted(resolved, key=lambda fp: fp.count(".")):
         sec, path, name = resolved[full_path]
         if cfgs[sec] is not None and _path_reachable(sec, path):
-            node = presets[sec][path][name]
+            node = _materialize_optional_preset(presets[sec][path][name])
             node_dict = (
                 node.to_dict() if hasattr(node, "to_dict") else dict(node) if isinstance(node, Mapping) else node
             )

source/isaaclab_tasks/isaaclab_tasks/utils/physics_presets.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Helpers for task physics backend presets."""
+
+from __future__ import annotations
+
+from isaaclab_tasks.utils.hydra import optional_preset
+
+
+def ovphysx_preset() -> object:
+    """Create the lazy optional preset for the OV-PhysX physics backend."""
+    return optional_preset(
+        "isaaclab_ovphysx.physics:OvPhysxCfg",
+        preset_name="ovphysx",
+        install_hint="Install the OV-PhysX optional backend before selecting the 'ovphysx' preset.",
+    )

source/isaaclab_tasks/test/test_hydra.py

@@ -9,6 +9,9 @@
 external environment configurations.
 """
 
+import sys
+import types
+
 import pytest
 
 from isaaclab.utils import configclass
@@ -17,6 +20,7 @@
     PresetCfg,
     apply_overrides,
     collect_presets,
+    optional_preset,
     parse_overrides,
     preset,
     resolve_presets,
@@ -570,6 +574,22 @@ class EnvWithOptionalFeatureCfg:
     optional_feature: OptionalFeaturePresetCfg = OptionalFeaturePresetCfg()
 
 
+@configclass
+class LazyOptionalBackendPresetCfg(PresetCfg):
+    default: PhysxCfg = PhysxCfg()
+    optional_backend = optional_preset(
+        "test_hydra_optional_backend:OptionalBackendCfg",
+        preset_name="optional_backend",
+        install_hint="Install the optional backend package.",
+    )
+
+
+@configclass
+class EnvWithLazyOptionalBackendCfg:
+    decimation: int = 4
+    backend: LazyOptionalBackendPresetCfg = LazyOptionalBackendPresetCfg()
+
+
 def test_presetcfg_none_default_auto_applies():
     """PresetCfg with default=None auto-applies None without crashing."""
     env_cfg, _ = _apply(EnvWithOptionalFeatureCfg())
@@ -588,6 +608,51 @@ def test_presetcfg_none_default_cli_selects_enabled():
     assert env_cfg.optional_feature.buffer_size == 200
 
 
+def test_optional_preset_default_does_not_import_missing_module():
+    """Optional preset alternatives are discoverable but not imported when default resolves."""
+    presets = collect_presets(EnvWithLazyOptionalBackendCfg())
+    assert "optional_backend" in presets["backend"]
+    assert "test_hydra_optional_backend" not in sys.modules
+
+    env_cfg = resolve_presets(EnvWithLazyOptionalBackendCfg())
+
+    assert isinstance(env_cfg.backend, PhysxCfg)
+    assert "test_hydra_optional_backend" not in sys.modules
+
+
+def test_optional_preset_selection_requires_installed_module():
+    """Selecting an unavailable optional preset raises an actionable import error."""
+    with pytest.raises(ModuleNotFoundError, match="Install the optional backend package."):
+        resolve_presets(EnvWithLazyOptionalBackendCfg(), {"optional_backend"})
+
+
+def test_optional_preset_path_selection_materializes_module(monkeypatch):
+    """Path selection imports and instantiates an available optional preset."""
+
+    @configclass
+    class OptionalBackendCfg:
+        backend: str = "optional"
+        substeps: int = 8
+
+    module = types.ModuleType("test_hydra_optional_backend")
+    module.OptionalBackendCfg = OptionalBackendCfg
+    monkeypatch.setitem(sys.modules, "test_hydra_optional_backend", module)
+
+    env_cfg = EnvWithLazyOptionalBackendCfg()
+    agent_cfg = PresetCfgAgentCfg()
+    presets = {"env": collect_presets(env_cfg), "agent": collect_presets(agent_cfg)}
+    hydra_cfg = {
+        "env": resolve_presets(EnvWithLazyOptionalBackendCfg()).to_dict(),
+        "agent": agent_cfg.to_dict(),
+    }
+
+    apply_overrides(env_cfg, agent_cfg, hydra_cfg, [], [("env", "backend", "optional_backend")], [], presets)
+
+    assert isinstance(env_cfg.backend, OptionalBackendCfg)
+    assert env_cfg.backend.backend == "optional"
+    assert hydra_cfg["env"]["backend"]["substeps"] == 8
+
+
 def test_root_presetcfg_global_depth_resolves_nested():
     """Global preset=depth on root PresetCfg also resolves nested sensor and renderer."""
     env_cfg, _ = _apply(RootPresetEnvCfg(), global_presets=["depth"])