fix: Upgrade teleop dependency during install

Read per-extension pip upgrade opt-ins from extension.toml so install.py can refresh selected install_requires dependencies without duplicating version specs.

Use uv --upgrade-package for targeted upgrades and keep pip behavior narrow, which lets CI pick up newer compatible isaacteleop releases without broad dependency churn.

Author: hougantc-nvda

docs/source/overview/developer-guide/development.rst

@@ -81,18 +81,21 @@ Custom Extension Dependency Management
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Certain extensions may have dependencies which require the installation of additional packages before the extension
-can be used. While Python dependencies are handled by the `setuptools <https://setuptools.pypa.io/en/latest/>`__
-package and specified in the ``setup.py`` file, non-Python dependencies such as `ROS <https://www.ros.org/>`__
-packages or `apt <https://en.wikipedia.org/wiki/APT_(software)>`__ packages are not handled by setuptools.
-Handling these kinds of dependencies requires an additional procedure.
+can be used. Python dependencies are handled by the `setuptools <https://setuptools.pypa.io/en/latest/>`__
+package and specified in the ``setup.py`` file. Non-Python dependencies such as
+`ROS <https://www.ros.org/>`__ packages or `apt <https://en.wikipedia.org/wiki/APT_(software)>`__
+packages are not handled by setuptools. Handling these kinds of dependencies requires an additional procedure.
 
-There are two types of dependencies that can be specified in the ``extension.toml`` file
+There are three types of dependencies that can be specified in the ``extension.toml`` file
 under the ``isaac_lab_settings`` section:
 
 1. **apt_deps**: A list of apt packages that need to be installed. These are installed using the
    `apt <https://ubuntu.com/server/docs/package-management>`__ package manager.
 2. **ros_ws**: The path to the ROS workspace that contains the ROS packages. These are installed using
    the `rosdep <https://docs.ros.org/en/humble/Tutorials/Intermediate/Rosdep.html>`__ dependency manager.
+3. **pip_upgrade_dependencies**: A list of ``install_requires`` dependency names that should be explicitly
+   upgraded after installing the extension with ``./isaaclab.sh --install``. List package names only. Version
+   ranges, extras, and platform markers are read from the installed extension metadata generated from ``setup.py``.
 
 As an example, the following ``extension.toml`` file specifies the dependencies for the extension:
 
@@ -106,8 +109,11 @@ As an example, the following ``extension.toml`` file specifies the dependencies
    # note: if this path is relative, it is relative to the extension directory's root
    ros_ws = "/home/user/catkin_ws"
 
-These dependencies are installed using the ``install_deps.py`` script provided in the ``tools`` directory.
-To install all dependencies for all extensions, run the following command:
+   # Python dependency names to upgrade after installing this extension
+   pip_upgrade_dependencies = ["example_package"]
+
+The ``apt_deps`` and ``ros_ws`` dependencies are installed using the ``install_deps.py`` script provided in the
+``tools`` directory. To install all apt and ROS dependencies for all extensions, run the following command:
 
 .. code-block:: bash
 
@@ -121,6 +127,9 @@ To install all dependencies for all extensions, run the following command:
    and ``Dockerfile.ros2``. This ensures that all the 'apt' and 'rosdep' dependencies are installed
    before building the extensions respectively.
 
+The ``pip_upgrade_dependencies`` entries are handled by ``./isaaclab.sh --install`` after the extension's editable
+pip install completes.
+
 
 Standalone applications
 ~~~~~~~~~~~~~~~~~~~~~~~

source/isaaclab/changelog.d/hougantc-enable-pipeline-retarget.rst

@@ -0,0 +1,5 @@
+Fixed
+^^^^^
+
+* Fixed extension installation to honor ``pip_upgrade_dependencies`` declared
+  in ``config/extension.toml``.

source/isaaclab/isaaclab/cli/commands/install.py

@@ -4,10 +4,13 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 import os
+import re
 import shutil
 import sys
 from pathlib import Path
 
+import tomllib
+
 from ..utils import (
     ISAACLAB_ROOT,
     extract_isaacsim_path,
@@ -286,6 +289,111 @@ def _ensure_cuda_torch() -> None:
 NVIDIA_INDEX_URL = "https://pypi.nvidia.com"
 
 
+def _normalize_package_name(name: str) -> str:
+    """Normalize a Python package name for metadata comparisons."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def _requirement_name(requirement: str) -> str:
+    """Extract the distribution name from a requirement string."""
+    requirement = requirement.split(";", 1)[0].strip()
+    return re.split(r"\s|<|>|=|!|~|\[|@", requirement, maxsplit=1)[0]
+
+
+def _get_installed_distribution_requirements(python_exe: str, distribution_name: str) -> list[str]:
+    """Return installed ``Requires-Dist`` requirements for a distribution."""
+    probe = """import importlib.metadata
+import sys
+
+try:
+    dist = importlib.metadata.distribution(sys.argv[1])
+except importlib.metadata.PackageNotFoundError:
+    sys.exit(1)
+
+for requirement in dist.requires or []:
+    print(requirement)
+"""
+    result = run_command(
+        [python_exe, "-c", probe, distribution_name],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print_warning(f"Could not read installed metadata for {distribution_name}; skipping dependency upgrades.")
+        return []
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def _get_extension_pip_upgrade_dependencies(extension_dir: Path) -> list[str]:
+    """Read dependency names opted into targeted pip upgrades from ``extension.toml``."""
+    extension_toml = extension_dir / "config" / "extension.toml"
+    if not extension_toml.is_file():
+        return []
+
+    try:
+        with extension_toml.open("rb") as fd:
+            extension_data = tomllib.load(fd)
+    except tomllib.TOMLDecodeError as exc:
+        print_warning(f"Could not parse {extension_toml}: {exc}; skipping targeted dependency upgrades.")
+        return []
+
+    isaac_lab_settings = extension_data.get("isaac_lab_settings", {})
+    if not isinstance(isaac_lab_settings, dict):
+        print_warning(
+            f"Ignoring invalid isaac_lab_settings in {extension_toml}; expected a table with pip_upgrade_dependencies."
+        )
+        return []
+
+    upgrade_dependencies = isaac_lab_settings.get("pip_upgrade_dependencies", [])
+    if not isinstance(upgrade_dependencies, list) or not all(isinstance(item, str) for item in upgrade_dependencies):
+        print_warning(f"Ignoring invalid pip_upgrade_dependencies in {extension_toml}; expected a list of strings.")
+        return []
+
+    return upgrade_dependencies
+
+
+def _get_pip_upgrade_command(pip_cmd: list[str], dependency_name: str, requirement: str) -> list[str]:
+    """Return a pip command that upgrades one dependency requirement."""
+    if pip_cmd[0] == "uv":
+        return pip_cmd + ["install", "--upgrade-package", dependency_name, requirement]
+    return pip_cmd + ["install", "--upgrade", requirement]
+
+
+def _upgrade_extension_pip_dependencies(
+    python_exe: str,
+    pip_cmd: list[str],
+    distribution_name: str,
+    dependency_names: list[str],
+) -> None:
+    """Upgrade selected dependencies using installed distribution metadata requirements."""
+    if not dependency_names:
+        return
+
+    requirements = _get_installed_distribution_requirements(python_exe, distribution_name)
+    seen_dependency_names = set()
+
+    for dependency_name in dependency_names:
+        normalized_dependency_name = _normalize_package_name(dependency_name)
+        if normalized_dependency_name in seen_dependency_names:
+            continue
+        seen_dependency_names.add(normalized_dependency_name)
+
+        matching_requirements = [
+            req for req in requirements if _normalize_package_name(_requirement_name(req)) == normalized_dependency_name
+        ]
+        if not matching_requirements:
+            print_warning(
+                f"Could not find dependency '{dependency_name}' in installed metadata for {distribution_name}; "
+                "skipping targeted upgrade."
+            )
+            continue
+
+        for requirement in matching_requirements:
+            print_info(f"Upgrading {dependency_name} for {distribution_name}: {requirement}")
+            run_command(_get_pip_upgrade_command(pip_cmd, dependency_name, requirement))
+
+
 def _install_isaacsim() -> None:
     """Install Isaac Sim pip package if not already present."""
     python_exe = extract_python_exe()
@@ -414,6 +522,12 @@ def _install_isaaclab_submodules(
         editable = (submodule_extras or {}).get(item.name, "")
         install_target = f"{item}{editable}"
         run_command(pip_cmd + ["install", "--editable", install_target])
+        _upgrade_extension_pip_dependencies(
+            python_exe,
+            pip_cmd,
+            item.name,
+            _get_extension_pip_upgrade_dependencies(item),
+        )
 
 
 def _install_extra_frameworks(framework_name: str = "all") -> None:

source/isaaclab/test/cli/test_install_commands.py

@@ -17,6 +17,7 @@
 
 import pytest
 
+import isaaclab.cli.commands.install as install_cmd
 from isaaclab.cli.commands.install import (
     _PREBUNDLE_REPOINT_PACKAGES,
     _ensure_cuda_torch,
@@ -68,6 +69,167 @@ def _make_site_packages(
     return site_pkgs
 
 
+# ---------------------------------------------------------------------------
+# _install_isaaclab_submodules targeted dependency upgrades
+# ---------------------------------------------------------------------------
+
+
+class TestInstallSubmodulesTargetedDependencyUpgrades:
+    """Tests for extension.toml-driven dependency upgrades."""
+
+    def _make_extension(self, tmp_path, extension_toml: str) -> Path:
+        """Create a minimal installable extension fixture."""
+        source_dir = tmp_path / "source"
+        extension_dir = source_dir / "isaaclab_teleop"
+        config_dir = extension_dir / "config"
+        config_dir.mkdir(parents=True)
+        (extension_dir / "setup.py").write_text("# test fixture\n", encoding="utf-8")
+        (config_dir / "extension.toml").write_text(extension_toml, encoding="utf-8")
+        return extension_dir
+
+    def test_installs_editable_then_upgrades_declared_dependency_from_metadata(self, tmp_path):
+        """An opted-in dependency is upgraded using the requirement recorded in installed metadata."""
+        extension_dir = self._make_extension(
+            tmp_path,
+            '[isaac_lab_settings]\npip_upgrade_dependencies = ["isaacteleop"]\n',
+        )
+
+        python_exe = str(tmp_path / "python")
+        pip_cmd = [python_exe, "-m", "pip"]
+        isaacteleop_req = 'isaacteleop[cloudxr,retargeters,ui] ~=1.2.0; platform_system == "Linux"'
+
+        with (
+            mock.patch("isaaclab.cli.commands.install.ISAACLAB_ROOT", tmp_path),
+            mock.patch("isaaclab.cli.commands.install.extract_python_exe", return_value=python_exe),
+            mock.patch("isaaclab.cli.commands.install.get_pip_command", return_value=pip_cmd),
+            mock.patch(
+                "isaaclab.cli.commands.install._get_installed_distribution_requirements",
+                return_value=[isaacteleop_req],
+            ),
+            mock.patch("isaaclab.cli.commands.install.run_command") as mock_run,
+        ):
+            install_cmd._install_isaaclab_submodules(["isaaclab_teleop"])
+
+        assert [call.args[0] for call in mock_run.call_args_list] == [
+            pip_cmd + ["install", "--editable", str(extension_dir)],
+            pip_cmd + ["install", "--upgrade", isaacteleop_req],
+        ]
+
+    def test_uv_install_uses_upgrade_package_for_declared_dependency(self, tmp_path):
+        """uv upgrades only the declared package rather than using a global upgrade."""
+        extension_dir = self._make_extension(
+            tmp_path,
+            '[isaac_lab_settings]\npip_upgrade_dependencies = ["isaacteleop"]\n',
+        )
+
+        python_exe = str(tmp_path / "python")
+        pip_cmd = ["uv", "pip"]
+        isaacteleop_req = 'isaacteleop[cloudxr,retargeters,ui] ~=1.2.0; platform_system == "Linux"'
+
+        with (
+            mock.patch("isaaclab.cli.commands.install.ISAACLAB_ROOT", tmp_path),
+            mock.patch("isaaclab.cli.commands.install.extract_python_exe", return_value=python_exe),
+            mock.patch("isaaclab.cli.commands.install.get_pip_command", return_value=pip_cmd),
+            mock.patch(
+                "isaaclab.cli.commands.install._get_installed_distribution_requirements",
+                return_value=[isaacteleop_req],
+            ),
+            mock.patch("isaaclab.cli.commands.install.run_command") as mock_run,
+        ):
+            install_cmd._install_isaaclab_submodules(["isaaclab_teleop"])
+
+        assert [call.args[0] for call in mock_run.call_args_list] == [
+            pip_cmd + ["install", "--editable", str(extension_dir)],
+            pip_cmd + ["install", "--upgrade-package", "isaacteleop", isaacteleop_req],
+        ]
+
+    def test_upgrades_all_matching_metadata_requirements(self, tmp_path):
+        """Duplicate metadata entries are preserved instead of collapsing to one requirement."""
+        python_exe = str(tmp_path / "python")
+        pip_cmd = [python_exe, "-m", "pip"]
+        linux_req = 'example-package>=1.0; platform_system == "Linux"'
+        windows_req = 'example_package>=2.0; platform_system == "Windows"'
+
+        with (
+            mock.patch(
+                "isaaclab.cli.commands.install._get_installed_distribution_requirements",
+                return_value=[linux_req, windows_req],
+            ),
+            mock.patch("isaaclab.cli.commands.install.run_command") as mock_run,
+        ):
+            install_cmd._upgrade_extension_pip_dependencies(
+                python_exe,
+                pip_cmd,
+                "isaaclab_teleop",
+                ["example-package"],
+            )
+
+        assert [call.args[0] for call in mock_run.call_args_list] == [
+            pip_cmd + ["install", "--upgrade", linux_req],
+            pip_cmd + ["install", "--upgrade", windows_req],
+        ]
+
+    def test_skips_duplicate_declared_dependency_names(self, tmp_path):
+        """Duplicate TOML dependency names do not trigger duplicate pip commands."""
+        python_exe = str(tmp_path / "python")
+        pip_cmd = [python_exe, "-m", "pip"]
+        req = "isaacteleop~=1.2.0"
+
+        with (
+            mock.patch(
+                "isaaclab.cli.commands.install._get_installed_distribution_requirements",
+                return_value=[req],
+            ),
+            mock.patch("isaaclab.cli.commands.install.run_command") as mock_run,
+        ):
+            install_cmd._upgrade_extension_pip_dependencies(
+                python_exe,
+                pip_cmd,
+                "isaaclab_teleop",
+                ["isaacteleop", "IsaacTeleop"],
+            )
+
+        mock_run.assert_called_once_with(pip_cmd + ["install", "--upgrade", req])
+
+    def test_skips_when_toml_has_no_upgrade_dependencies(self, tmp_path):
+        """Extensions without pip upgrade opt-ins do not trigger metadata probes."""
+        extension_dir = self._make_extension(tmp_path, "[isaac_lab_settings]\n")
+
+        assert install_cmd._get_extension_pip_upgrade_dependencies(extension_dir) == []
+
+    def test_warns_and_skips_invalid_upgrade_dependency_names(self, tmp_path):
+        """Invalid TOML value types warn and disable targeted upgrades."""
+        extension_dir = self._make_extension(
+            tmp_path,
+            '[isaac_lab_settings]\npip_upgrade_dependencies = "isaacteleop"\n',
+        )
+
+        with mock.patch("isaaclab.cli.commands.install.print_warning") as mock_warning:
+            assert install_cmd._get_extension_pip_upgrade_dependencies(extension_dir) == []
+
+        mock_warning.assert_called_once()
+
+    def test_warns_when_declared_dependency_missing_from_metadata(self, tmp_path):
+        """A declared dependency name must exist in installed package metadata."""
+        with (
+            mock.patch(
+                "isaaclab.cli.commands.install._get_installed_distribution_requirements",
+                return_value=["dex-retargeting==0.5.0"],
+            ),
+            mock.patch("isaaclab.cli.commands.install.print_warning") as mock_warning,
+            mock.patch("isaaclab.cli.commands.install.run_command") as mock_run,
+        ):
+            install_cmd._upgrade_extension_pip_dependencies(
+                str(tmp_path / "python"),
+                [str(tmp_path / "python"), "-m", "pip"],
+                "isaaclab_teleop",
+                ["isaacteleop"],
+            )
+
+        mock_warning.assert_called_once()
+        mock_run.assert_not_called()
+
+
 # ---------------------------------------------------------------------------
 # _torch_first_on_sys_path_is_prebundle
 # ---------------------------------------------------------------------------

source/isaaclab_teleop/changelog.d/hougantc-pipelined-retargeting.rst

@@ -15,3 +15,9 @@ Changed
   Isaac Lab's step Python. Set
   ``retargeting_execution=RetargetingExecutionConfig(mode="sync")`` to restore
   exact current-frame retargeting.
+
+Fixed
+^^^^^
+
+* Fixed installation to upgrade to the latest compatible ``isaacteleop``
+  package when installing ``isaaclab_teleop``.

source/isaaclab_teleop/config/extension.toml

@@ -13,6 +13,10 @@ keywords = ["kit", "robotics", "teleoperation", "xr", "isaaclab"]
 [dependencies]
 "isaaclab" = {}
 
+[isaac_lab_settings]
+# Names only. Version ranges, extras, and platform markers come from setup.py metadata.
+pip_upgrade_dependencies = ["isaacteleop"]
+
 [core]
 reloadable = false