Warp-first experimental envs implements lazy export + cfg implementation split

source/isaaclab/changelog.d/fix-warp-env-cfg-forbidden-imports.skip

@@ -0,0 +1,3 @@
+Internal: hoisted module-local backend imports (``pxr``/``sim_utils``) to module top in
+implementation files (``scene_data/scene_data_provider``, ``sim/schemas/schemas_actuators``,
+``envs/utils/camera_view``, ``terrains/utils``). No user-facing change.

source/isaaclab/isaaclab/envs/utils/camera_view.py

@@ -14,10 +14,11 @@
 import torch
 import warp as wp
 
-from pxr import Sdf
+from pxr import Sdf, UsdGeom
 
 import isaaclab.sim as sim_utils
 from isaaclab.sensors.camera import Camera, CameraCfg
+from isaaclab.sim.views import FrameView
 
 _GENERATED_CAMERA_NAME = "VisualizerCamera"
 VISUALIZER_TILED_CAMERA_MAX_TILES = 100
@@ -225,10 +226,6 @@ def prim_world_positions(
     Uses ``FrameView`` first so PhysX/Fabric-backed transforms are current; falls
     back to USD only if the backend view cannot be constructed.
     """
-    from pxr import UsdGeom
-
-    from isaaclab.sim.views import FrameView
-
     xform_cache = UsdGeom.XformCache()
     positions = []
     try:

source/isaaclab/isaaclab/scene_data/scene_data_provider.py

@@ -13,6 +13,10 @@
 import numpy as np
 import warp as wp
 
+from pxr import UsdGeom
+
+import isaaclab.sim as sim_utils
+
 from .scene_data_backend import SceneDataBackend, SceneDataFormat
 
 if TYPE_CHECKING:
@@ -425,10 +429,6 @@ def _walk_camera_prims(stage: Usd.Stage | None) -> dict[str, Any] | None:
     if stage is None:
         return None
 
-    from pxr import UsdGeom
-
-    import isaaclab.sim as isaaclab_sim
-
     shared_paths: list[str] = []
     instances: dict[str, list[tuple[int, str]]] = {}
     num_envs = -1
@@ -475,7 +475,7 @@ def _walk_camera_prims(stage: Usd.Stage | None) -> dict[str, Any] | None:
             prim = stage.GetPrimAtPath(prim_path)
             if not prim.IsValid():
                 continue
-            pos, ori = isaaclab_sim.resolve_prim_pose(prim)
+            pos, ori = sim_utils.resolve_prim_pose(prim)
             per_world_pos[world_id] = [float(pos[0]), float(pos[1]), float(pos[2])]
             per_world_ori[world_id] = [float(ori[0]), float(ori[1]), float(ori[2]), float(ori[3])]
         positions.append(per_world_pos)

source/isaaclab/isaaclab/sim/schemas/schemas_actuators.py

@@ -24,6 +24,11 @@
 import re
 from typing import Any
 
+from pxr import Sdf, Usd
+
+from isaaclab.actuators import ImplicitActuator
+from isaaclab.utils.string import resolve_matching_names
+
 logger = logging.getLogger(__name__)
 
 
@@ -134,11 +139,6 @@ def _author_actuator_prims(
     actuator_cfgs: dict[str, Any],
 ) -> None:
     """Inner authoring routine; exposed separately for test fixtures."""
-    from pxr import Sdf  # noqa: PLC0415
-
-    from isaaclab.actuators import ImplicitActuator  # noqa: PLC0415
-    from isaaclab.utils.string import resolve_matching_names  # noqa: PLC0415
-
     art_prim = stage.GetPrimAtPath(articulation_prim_path)
     if not art_prim.IsValid():
         raise ValueError(f"Articulation prim not found: {articulation_prim_path}")
@@ -300,8 +300,6 @@ def _collect_joint_prims(art_prim: Any) -> dict[str, str]:
     Returns:
         Ordered mapping of joint name to full prim path.
     """
-    from pxr import Usd  # noqa: PLC0415
-
     _JOINT_TYPES = {"PhysicsRevoluteJoint", "PhysicsPrismaticJoint"}
 
     joints: dict[str, str] = {}
@@ -324,8 +322,6 @@ def _remove_actuator_prims_for_joints(
 
     Only prims under the *art_prim* subtree are considered.
     """
-    from pxr import Usd  # noqa: PLC0415
-
     to_deactivate: list = []
     for prim in Usd.PrimRange(art_prim):
         if prim.GetTypeName() != "NewtonActuator":

source/isaaclab/isaaclab/terrains/utils.py

@@ -11,6 +11,9 @@
 import trimesh
 import warp as wp
 
+from pxr import UsdGeom
+
+import isaaclab.sim as sim_utils
 from isaaclab.utils.warp import raycast_mesh
 
 
@@ -78,11 +81,6 @@ def create_prim_from_mesh(prim_path: str, mesh: trimesh.Trimesh, **kwargs):
         visual_material: The visual material to apply. Defaults to None.
         physics_material: The physics material to apply. Defaults to None.
     """
-    # need to import these here to prevent isaacsim launching when importing this module
-    from pxr import UsdGeom
-
-    import isaaclab.sim as sim_utils
-
     # create parent prim
     sim_utils.create_prim(prim_path, "Xform")
     # create mesh prim

source/isaaclab_experimental/changelog.d/fix-warp-env-cfg-forbidden-imports.rst

@@ -0,0 +1,10 @@
+Fixed
+^^^^^
+
+* Fixed the experimental packages eagerly importing backend modules (``pxr``,
+  ``omni``, ``carb``, ``isaacsim``, ``scipy``) at import time, which crashed when
+  a warp task's env config was loaded before ``SimulationApp`` was launched. The
+  ``managers``, ``envs``, ``envs.mdp`` and ``envs.mdp.actions`` packages now use
+  ``lazy_export`` with ``.pyi`` stubs, and the MDP term leaf modules guard runtime
+  types (``Articulation``, ``InteractiveScene``, ``ContactSensor``, action terms)
+  under ``TYPE_CHECKING`` with string ``class_type`` references.

source/isaaclab_experimental/isaaclab_experimental/envs/__init__.py

@@ -42,14 +42,6 @@
 .. _`Task Design Workflows`: https://isaac-sim.github.io/IsaacLab/source/features/task_workflows.html
 """
 
-from .direct_rl_env_warp import DirectRLEnvWarp  # noqa: F401
-from .interactive_scene_warp import InteractiveSceneWarp  # noqa: F401
-from .manager_based_env_warp import ManagerBasedEnvWarp  # noqa: F401
-from .manager_based_rl_env_warp import ManagerBasedRLEnvWarp  # noqa: F401
-
-__all__ = [
-    "DirectRLEnvWarp",
-    "InteractiveSceneWarp",
-    "ManagerBasedEnvWarp",
-    "ManagerBasedRLEnvWarp",
-]
+from isaaclab.utils.module import lazy_export
+
+lazy_export()

source/isaaclab_experimental/isaaclab_experimental/envs/__init__.pyi

@@ -0,0 +1,18 @@
+# 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
+
+__all__ = [
+    "mdp",
+    "DirectRLEnvWarp",
+    "InteractiveSceneWarp",
+    "ManagerBasedEnvWarp",
+    "ManagerBasedRLEnvWarp",
+]
+
+from . import mdp
+from .direct_rl_env_warp import DirectRLEnvWarp
+from .interactive_scene_warp import InteractiveSceneWarp
+from .manager_based_env_warp import ManagerBasedEnvWarp
+from .manager_based_rl_env_warp import ManagerBasedRLEnvWarp

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/__init__.py

@@ -9,18 +9,6 @@
 functions with Warp-first implementations from :mod:`isaaclab_experimental.envs.mdp.rewards`.
 """
 
-# Forward stable MDP terms (commands/observations/terminations/etc.) but *exclude* rewards and actions.
-# Rewards and actions are provided by this experimental package to keep Warp-first execution.
-from isaaclab.envs.mdp.commands import *  # noqa: F401, F403
-from isaaclab.envs.mdp.curriculums import *  # noqa: F401, F403
-from isaaclab.envs.mdp.events import *  # noqa: F401, F403
-from isaaclab.envs.mdp.observations import *  # noqa: F401, F403
-from isaaclab.envs.mdp.recorders import *  # noqa: F401, F403
-from isaaclab.envs.mdp.terminations import *  # noqa: F401, F403
+from isaaclab.utils.module import lazy_export
 
-# Override terms with experimental implementations.
-from .actions import *  # noqa: F401, F403
-from .events import *  # noqa: F401, F403
-from .observations import *  # noqa: F401, F403
-from .rewards import *  # noqa: F401, F403
-from .terminations import *  # noqa: F401, F403
+lazy_export()

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/__init__.pyi

@@ -0,0 +1,29 @@
+# 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
+
+# Forward all stable MDP terms (commands/curriculums/events/observations/...) via a
+# lazy fallback, so unresolved names defer to the stable package without eagerly
+# importing its backend-dependent submodules.
+from isaaclab.envs.mdp import *  # noqa: F401, F403
+
+# Experimental Warp-first action terms. Listed by name (not ``*``) so the runtime
+# implementations in ``joint_actions`` stay lazy and only the pure-data config
+# classes are imported when an env config is constructed.
+from .actions import (  # noqa: F401
+    JointAction,
+    JointActionCfg,
+    JointEffortAction,
+    JointEffortActionCfg,
+    JointPositionAction,
+    JointPositionActionCfg,
+)
+
+# Override stable terms with experimental Warp-first implementations. These leaf
+# modules are import-clean (no eager backend imports), so re-exporting them here
+# is safe.
+from .events import *  # noqa: F401, F403
+from .observations import *  # noqa: F401, F403
+from .rewards import *  # noqa: F401, F403
+from .terminations import *  # noqa: F401, F403

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/actions/__init__.py

@@ -7,7 +7,12 @@
 
 Provides Warp-first action term implementations overriding the stable
 :mod:`isaaclab.envs.mdp.actions` module.
+
+Symbols are lazily resolved from the ``__init__.pyi`` stub so that importing the
+pure-data action config classes does not eagerly pull in the runtime action term
+implementations (which depend on a running simulator).
 """
 
-from .actions_cfg import *  # noqa: F401, F403
-from .joint_actions import *  # noqa: F401, F403
+from isaaclab.utils.module import lazy_export
+
+lazy_export()

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/actions/__init__.pyi

@@ -0,0 +1,16 @@
+# 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
+
+__all__ = [
+    "JointAction",
+    "JointActionCfg",
+    "JointEffortAction",
+    "JointEffortActionCfg",
+    "JointPositionAction",
+    "JointPositionActionCfg",
+]
+
+from .actions_cfg import JointActionCfg, JointEffortActionCfg, JointPositionActionCfg
+from .joint_actions import JointAction, JointEffortAction, JointPositionAction

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/actions/actions_cfg.py

@@ -3,13 +3,17 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
+from __future__ import annotations
+
 from dataclasses import MISSING
+from typing import TYPE_CHECKING
 
 from isaaclab.utils.configclass import configclass
 
-from isaaclab_experimental.managers.action_manager import ActionTerm, ActionTermCfg
+from isaaclab_experimental.managers.manager_term_cfg import ActionTermCfg
 
-from . import joint_actions
+if TYPE_CHECKING:
+    from .joint_actions import JointEffortAction, JointPositionAction
 
 ##
 # Joint actions.
@@ -40,7 +44,7 @@ class JointPositionActionCfg(JointActionCfg):
     See :class:`JointPositionAction` for more details.
     """
 
-    class_type: type[ActionTerm] = joint_actions.JointPositionAction
+    class_type: type[JointPositionAction] | str = "{DIR}.joint_actions:JointPositionAction"
 
     use_default_offset: bool = True
     """Whether to use default joint positions configured in the articulation asset as offset.
@@ -58,4 +62,4 @@ class JointEffortActionCfg(JointActionCfg):
     See :class:`JointEffortAction` for more details.
     """
 
-    class_type: type[ActionTerm] = joint_actions.JointEffortAction
+    class_type: type[JointEffortAction] | str = "{DIR}.joint_actions:JointEffortAction"

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/events.py

@@ -24,13 +24,16 @@
 
 from __future__ import annotations
 
-import warp as wp
+from typing import TYPE_CHECKING
 
-from isaaclab.assets import Articulation
+import warp as wp
 
 from isaaclab_experimental.managers import SceneEntityCfg
 from isaaclab_experimental.utils.warp import WarpCapturable
 
+if TYPE_CHECKING:
+    from isaaclab.assets import Articulation
+
 # ---------------------------------------------------------------------------
 # Randomize rigid body center of mass
 # ---------------------------------------------------------------------------

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/observations.py

@@ -27,8 +27,6 @@
     rotate_vec_to_body_frame,
 )
 
-from isaaclab.assets import Articulation
-
 from isaaclab_experimental.envs.utils.io_descriptors import (
     generic_io_descriptor_warp,
     record_dtype,
@@ -40,6 +38,7 @@
 from isaaclab_experimental.managers import SceneEntityCfg
 
 if TYPE_CHECKING:
+    from isaaclab.assets import Articulation
     from isaaclab.envs import ManagerBasedEnv
 
 

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/rewards.py

@@ -24,11 +24,10 @@
     rotate_vec_to_body_frame,
 )
 
-from isaaclab.assets import Articulation
-
 from isaaclab_experimental.managers import SceneEntityCfg
 
 if TYPE_CHECKING:
+    from isaaclab.assets import Articulation
     from isaaclab.envs import ManagerBasedRLEnv
 
 

source/isaaclab_experimental/isaaclab_experimental/envs/mdp/terminations.py

@@ -19,11 +19,10 @@
 
 import warp as wp
 
-from isaaclab.assets import Articulation
-
 from isaaclab_experimental.managers import SceneEntityCfg
 
 if TYPE_CHECKING:
+    from isaaclab.assets import Articulation
     from isaaclab.envs import ManagerBasedRLEnv
 
 

source/isaaclab_experimental/isaaclab_experimental/managers/__init__.py

@@ -7,18 +7,14 @@
 
 This package is intended for experimental forks of manager implementations while
 keeping stable task configs and the stable `isaaclab.managers` package intact.
-"""
 
-from isaaclab.managers import *  # noqa: F401,F403
+Symbols are lazily resolved from the ``__init__.pyi`` stub so that importing this
+package (e.g. to access pure-data cfg types like
+:class:`~isaaclab_experimental.managers.ObservationTermCfg`) does not eagerly
+pull in runtime managers that depend on a running simulator. This mirrors the
+stable :mod:`isaaclab.managers` package.
+"""
 
-from .action_manager import ActionManager  # noqa: F401
-from .command_manager import CommandManager  # noqa: F401
-from .event_manager import EventManager  # noqa: F401
+from isaaclab.utils.module import lazy_export
 
-# Override the stable implementation with the experimental fork.
-from .manager_base import ManagerTermBase  # noqa: F401
-from .manager_term_cfg import ObservationTermCfg, RewardTermCfg, TerminationTermCfg  # noqa: F401
-from .observation_manager import ObservationManager  # noqa: F401
-from .reward_manager import RewardManager  # noqa: F401
-from .scene_entity_cfg import SceneEntityCfg  # noqa: F401
-from .termination_manager import TerminationManager  # noqa: F401
+lazy_export()