[3.0.0-beta2] Fix ModuleNotFoundError: No module named 'isaacteleop' when parsing teleop env configs (#6116)

# Description

Fixes a `ModuleNotFoundError: No module named 'isaacteleop'` that made
several teleop-enabled
environments crash at parse time on systems where `isaacteleop` is not
installed (e.g. DGX
Spark). This broke the following documented QA workflows:
- `Isaac-NutPour-GR1T2-Pink-IK-Abs-v0` via `play.py`
- `Isaac-G1-SteeringWheel-Locomanipulation` via SDG `generate_data.py`
- G1 locomanipulation Mimic `generate_dataset.py`
The root cause was in `isaaclab_teleop/isaac_teleop_cfg.py`, which
imported
`isaacteleop.teleop_session_manager` at **module load time**. Because
`parse_env_cfg` both
imports and instantiates env configs, any env referencing
`IsaacTeleopCfg` raised the error
before any simulation code ran.

Fixes # (issue)

## Type of change

- Bug fix (non-breaking change which fixes an issue)

## Checklist

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

Author: rwiltz

source/isaaclab_tasks/changelog.d/remove-teleop-import-guards.rst

@@ -0,0 +1,11 @@
+Changed
+^^^^^^^
+
+* Removed the per-environment ``try/except ImportError`` guards around the
+  ``isaacteleop`` / ``isaaclab_teleop`` imports in the Galbot, Franka, GR1T2
+  nut-pour, and GR1T2 exhaust-pipe task configs. The imports are now
+  unconditional, matching the other teleop task configs, now that
+  :class:`~isaaclab_teleop.IsaacTeleopCfg` no longer requires the optional
+  ``isaacteleop`` package at import time. No migration is needed:
+  ``isaaclab_teleop`` ships with Isaac Lab and teleoperation behavior is
+  unchanged.

source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation/pick_place/exhaustpipe_gr1t2_base_env_cfg.py

@@ -3,17 +3,14 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-import logging
 import tempfile
 from dataclasses import MISSING
 
-try:
-    from isaaclab_teleop import XrCfg
+from isaaclab_teleop import XrCfg
 
-    _TELEOP_AVAILABLE = True
-except ImportError:
-    _TELEOP_AVAILABLE = False
-    logging.getLogger(__name__).warning("isaaclab_teleop is not installed. XR teleoperation features will be disabled.")
+# Marker consumed by ``env_test_utils._is_teleop_env`` to bucket teleop
+# environments in the test suite.
+_TELEOP_AVAILABLE = True
 
 import isaaclab.envs.mdp as base_mdp
 import isaaclab.sim as sim_utils
@@ -328,8 +325,7 @@ def __post_init__(self):
         # List of image observations in policy observations
         self.image_obs_list = ["robot_pov_cam"]
 
-        if _TELEOP_AVAILABLE:
-            self.xr = XrCfg(
-                anchor_pos=(0.0, 0.0, 0.0),
-                anchor_rot=(0.0, 0.0, 0.0, 1.0),
-            )
+        self.xr = XrCfg(
+            anchor_pos=(0.0, 0.0, 0.0),
+            anchor_rot=(0.0, 0.0, 0.0, 1.0),
+        )

source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation/pick_place/nutpour_gr1t2_base_env_cfg.py

@@ -3,17 +3,14 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-import logging
 import tempfile
 from dataclasses import MISSING
 
-try:
-    from isaaclab_teleop import XrCfg
+from isaaclab_teleop import XrCfg
 
-    _TELEOP_AVAILABLE = True
-except ImportError:
-    _TELEOP_AVAILABLE = False
-    logging.getLogger(__name__).warning("isaaclab_teleop is not installed. XR teleoperation features will be disabled.")
+# Marker consumed by ``env_test_utils._is_teleop_env`` to bucket teleop
+# environments in the test suite.
+_TELEOP_AVAILABLE = True
 
 import isaaclab.envs.mdp as base_mdp
 import isaaclab.sim as sim_utils
@@ -363,8 +360,7 @@ def __post_init__(self):
         # List of image observations in policy observations
         self.image_obs_list = ["robot_pov_cam"]
 
-        if _TELEOP_AVAILABLE:
-            self.xr = XrCfg(
-                anchor_pos=(0.0, 0.0, 0.0),
-                anchor_rot=(0.0, 0.0, 0.0, 1.0),
-            )
+        self.xr = XrCfg(
+            anchor_pos=(0.0, 0.0, 0.0),
+            anchor_rot=(0.0, 0.0, 0.0, 1.0),
+        )

source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation/stack/config/franka/stack_ik_abs_env_cfg.py

@@ -3,20 +3,15 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-import logging
+from isaaclab_teleop import IsaacTeleopCfg
 
 from isaaclab.controllers.differential_ik_cfg import DifferentialIKControllerCfg
 from isaaclab.envs.mdp.actions.actions_cfg import DifferentialInverseKinematicsActionCfg
 from isaaclab.utils.configclass import configclass
 
-try:
-    import isaacteleop  # noqa: F401  -- pipeline builders need isaacteleop at runtime
-    from isaaclab_teleop import IsaacTeleopCfg
-
-    _TELEOP_AVAILABLE = True
-except ImportError:
-    _TELEOP_AVAILABLE = False
-    logging.getLogger(__name__).warning("isaaclab_teleop is not installed. XR teleoperation features will be disabled.")
+# Marker consumed by ``env_test_utils._is_teleop_env`` to bucket teleop
+# environments in the test suite.
+_TELEOP_AVAILABLE = True
 
 from . import stack_joint_pos_env_cfg
 
@@ -130,9 +125,8 @@ def __post_init__(self):
         )
 
         # IsaacTeleop-based teleoperation pipeline
-        if _TELEOP_AVAILABLE:
-            self.isaac_teleop = IsaacTeleopCfg(
-                pipeline_builder=_build_franka_stack_pipeline,
-                sim_device=self.sim.device,
-                xr_cfg=self.xr,
-            )
+        self.isaac_teleop = IsaacTeleopCfg(
+            pipeline_builder=_build_franka_stack_pipeline,
+            sim_device=self.sim.device,
+            xr_cfg=self.xr,
+        )

source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation/stack/config/galbot/stack_joint_pos_env_cfg.py

@@ -4,9 +4,8 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 
-import logging
-
 from isaaclab_physx.assets import SurfaceGripperCfg
+from isaaclab_teleop import IsaacTeleopCfg
 
 from isaaclab.assets import RigidObjectCfg
 from isaaclab.envs.mdp.actions.actions_cfg import SurfaceGripperBinaryActionCfg
@@ -29,14 +28,9 @@
     raise_if_surface_gripper_on_newton,
 )
 
-try:
-    import isaacteleop  # noqa: F401  -- pipeline builders need isaacteleop at runtime
-    from isaaclab_teleop import IsaacTeleopCfg
-
-    _TELEOP_AVAILABLE = True
-except ImportError:
-    _TELEOP_AVAILABLE = False
-    logging.getLogger(__name__).warning("isaaclab_teleop is not installed. XR teleoperation features will be disabled.")
+# Marker consumed by ``env_test_utils._is_teleop_env`` to bucket teleop
+# environments in the test suite.
+_TELEOP_AVAILABLE = True
 
 ##
 # Pre-defined configs
@@ -342,12 +336,11 @@ def __post_init__(self):
         )
 
         # IsaacTeleop-based teleoperation pipeline (left hand)
-        if _TELEOP_AVAILABLE:
-            self.isaac_teleop = IsaacTeleopCfg(
-                pipeline_builder=lambda: _build_se3_abs_gripper_pipeline(hand_side="left"),
-                sim_device=self.sim.device,
-                xr_cfg=self.xr,
-            )
+        self.isaac_teleop = IsaacTeleopCfg(
+            pipeline_builder=lambda: _build_se3_abs_gripper_pipeline(hand_side="left"),
+            sim_device=self.sim.device,
+            xr_cfg=self.xr,
+        )
 
 
 @configclass
@@ -388,9 +381,8 @@ def __post_init__(self):
         self.scene.ee_frame.target_frames[0].prim_path = "{ENV_REGEX_NS}/Robot/right_suction_cup_tcp_link"
 
         # IsaacTeleop-based teleoperation pipeline (right hand)
-        if _TELEOP_AVAILABLE:
-            self.isaac_teleop = IsaacTeleopCfg(
-                pipeline_builder=lambda: _build_se3_abs_gripper_pipeline(hand_side="right"),
-                sim_device=self.sim.device,
-                xr_cfg=self.xr,
-            )
+        self.isaac_teleop = IsaacTeleopCfg(
+            pipeline_builder=lambda: _build_se3_abs_gripper_pipeline(hand_side="right"),
+            sim_device=self.sim.device,
+            xr_cfg=self.xr,
+        )

source/isaaclab_teleop/changelog.d/dont-fail-on-isaacteleop-missing.rst

@@ -0,0 +1,10 @@
+Fixed
+^^^^^
+
+* Fixed :class:`~isaaclab_teleop.IsaacTeleopCfg` requiring the optional ``isaacteleop``
+  package at import and construction time. Environments that reference it (e.g. the GR1T2
+  and Unitree G1 pick-place and locomanipulation tasks) failed to parse with
+  ``No module named 'isaacteleop'`` on systems where ``isaacteleop`` is not installed
+  (e.g. DGX Spark). The ``isaacteleop`` import is now deferred, and
+  :attr:`~isaaclab_teleop.IsaacTeleopCfg.retargeting_execution` defaults to ``None`` and is
+  resolved to IsaacTeleop's pipelined, deadline-paced default when a teleop session starts.

source/isaaclab_teleop/docs/README.md

@@ -120,7 +120,7 @@ rendering without blocking.
 | `retargeters_to_tune` | `Callable[[], list[BaseRetargeter]] \| None` | `None` | Retargeters to expose in the tuning UI |
 | `plugins` | `list[PluginConfig]` | `[]` | IsaacTeleop plugin configurations |
 | `sim_device` | `str` | `"cuda:0"` | Torch device for output action tensors |
-| `retargeting_execution` | `RetargetingExecutionConfig` | `mode="pipelined", pacing=DeadlinePacingConfig(safety_margin_s=0.025)` | IsaacTeleop retargeting execution settings |
+| `retargeting_execution` | `RetargetingExecutionConfig \| None` | `None` (resolved at session start to `mode="pipelined", pacing=DeadlinePacingConfig(safety_margin_s=0.025)`) | IsaacTeleop retargeting execution settings; deferred so the config imports without `isaacteleop` |
 | `teleoperation_active_default` | `bool` | `False` | Whether teleoperation is active on session start |
 | `app_name` | `str` | `"IsaacLabTeleop"` | Application name for the IsaacTeleop session |
 

source/isaaclab_teleop/isaaclab_teleop/isaac_teleop_cfg.py

@@ -12,8 +12,6 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from isaacteleop.teleop_session_manager import DeadlinePacingConfig, RetargetingExecutionConfig
-
 from isaaclab.utils.configclass import configclass
 
 from .control_events import TELEOP_CONTROL_CHANNEL_UUID
@@ -29,7 +27,7 @@
 
 if TYPE_CHECKING:
     from isaacteleop.retargeting_engine.interface import BaseRetargeter, OutputCombiner
-    from isaacteleop.teleop_session_manager import PluginConfig
+    from isaacteleop.teleop_session_manager import PluginConfig, RetargetingExecutionConfig
 
 
 @configclass
@@ -97,16 +95,16 @@ def build_pipeline():
     sim_device: str = "cuda:0"
     """Torch device string for placing output action tensors."""
 
-    retargeting_execution: RetargetingExecutionConfig = field(
-        default_factory=lambda: RetargetingExecutionConfig(
-            mode="pipelined",
-            pacing=DeadlinePacingConfig(safety_margin_s=0.025),
-        )
-    )
+    retargeting_execution: RetargetingExecutionConfig | None = None
     """IsaacTeleop retargeting execution settings.
 
-    Isaac Lab opts into IsaacTeleop's pipelined execution by default. Set this
-    to ``RetargetingExecutionConfig(mode="sync")`` for exact current-frame
+    Left as ``None`` by default so that importing and constructing this config
+    never requires the optional ``isaacteleop`` package (e.g. on platforms where
+    it is not installed). When ``None``, Isaac Lab resolves it at session start to
+    IsaacTeleop's pipelined, deadline-paced default
+    (``RetargetingExecutionConfig(mode="pipelined", pacing=DeadlinePacingConfig(safety_margin_s=0.025))``),
+    where ``isaacteleop`` is guaranteed to be available. Set this explicitly to
+    ``RetargetingExecutionConfig(mode="sync")`` for exact current-frame
     retargeting while debugging or comparing behavior.
     """
 

source/isaaclab_teleop/isaaclab_teleop/session_lifecycle.py

@@ -502,6 +502,21 @@ def try_start_session(self) -> bool:
         """
         return self._try_start_session()
 
+    def _resolved_retargeting_execution(self):
+        """Return the retargeting execution settings for the IsaacTeleop session.
+
+        :attr:`~isaaclab_teleop.IsaacTeleopCfg.retargeting_execution` defaults to
+        ``None`` so that constructing the config never requires the optional
+        ``isaacteleop`` package. The default is resolved here, at session-start
+        time, where ``isaacteleop`` is guaranteed to be importable.
+        """
+        if self._cfg.retargeting_execution is not None:
+            return self._cfg.retargeting_execution
+
+        from isaacteleop.teleop_session_manager import DeadlinePacingConfig, RetargetingExecutionConfig
+
+        return RetargetingExecutionConfig(mode="pipelined", pacing=DeadlinePacingConfig(safety_margin_s=0.025))
+
     def _try_start_session(self) -> bool:
         """Attempt to create and start the IsaacTeleop session.
 
@@ -563,7 +578,7 @@ def _try_start_session(self) -> bool:
             teleop_control_pipeline=self._teleop_control_pipeline,
             plugins=self._cfg.plugins,
             oxr_handles=oxr_handles,
-            retargeting_execution=self._cfg.retargeting_execution,
+            retargeting_execution=self._resolved_retargeting_execution(),
             mcap_config=mcap_config,
         )
 
@@ -611,7 +626,7 @@ def _start_replay_session(self) -> bool:
             pipeline=self._pipeline,
             teleop_control_pipeline=self._teleop_control_pipeline,
             plugins=self._cfg.plugins,
-            retargeting_execution=self._cfg.retargeting_execution,
+            retargeting_execution=self._resolved_retargeting_execution(),
             mode=SessionMode.REPLAY,
             mcap_config=mcap_config,
         )

source/isaaclab_teleop/test/test_cloudxr_lifecycle.py

@@ -189,13 +189,12 @@ class TestRetargetingExecutionConfig:
     """Tests for Isaac Lab's IsaacTeleop retargeting execution defaults."""
 
     def test_session_config_receives_deadline_paced_pipelined_retargeting(self):
-        """The default retargeting execution config is passed into TeleopSession."""
+        """An unset retargeting execution config resolves to the pipelined default at session start."""
         cfg = _make_cfg()
 
-        assert cfg.retargeting_execution.mode == "pipelined"
-        assert cfg.retargeting_execution.pacing.safety_margin_s == 0.025
-
-        sentinel_execution = cfg.retargeting_execution
+        # The default is deferred (``None``) so that constructing the config never
+        # requires the optional ``isaacteleop`` package.
+        assert cfg.retargeting_execution is None
 
         lifecycle = TeleopSessionLifecycle(cfg)
         lifecycle._pipeline = MagicMock()
@@ -213,7 +212,9 @@ def test_session_config_receives_deadline_paced_pipelined_retargeting(self):
         ):
             assert lifecycle.try_start_session() is True
 
-        assert session_config_cls.call_args.kwargs["retargeting_execution"] is sentinel_execution
+        resolved_execution = session_config_cls.call_args.kwargs["retargeting_execution"]
+        assert resolved_execution.mode == "pipelined"
+        assert resolved_execution.pacing.safety_margin_s == 0.025
 
 
 # ============================================================================