diff --git a/docs/source/setup/installation/include/pip_python_virtual_env.rst b/docs/source/setup/installation/include/pip_python_virtual_env.rst index 43b625293bb..8791a981228 100644 --- a/docs/source/setup/installation/include/pip_python_virtual_env.rst +++ b/docs/source/setup/installation/include/pip_python_virtual_env.rst @@ -73,7 +73,7 @@ If you wish to install Isaac Sim 5.X, please use modify the instructions accordi :: activate the virtual environment env_isaaclab\Scripts\activate - .. tab-item:: UV Environment (experimental) + .. tab-item:: UV Environment To install ``uv``, please follow the instructions `here `__. diff --git a/docs/source/setup/installation/include/src_build_isaaclab.rst b/docs/source/setup/installation/include/src_build_isaaclab.rst index a20d8bb9f72..ffb2bf5d7dd 100644 --- a/docs/source/setup/installation/include/src_build_isaaclab.rst +++ b/docs/source/setup/installation/include/src_build_isaaclab.rst @@ -37,7 +37,7 @@ Installation isaaclab.bat --install :: or "isaaclab.bat -i" - By default, the above will install **all** the learning frameworks. These include + By default, the above will install **all** the learning framework and all Isaac Lab sub-packages (under ``source/isaaclab``). Available RL frameworks are: ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``. If you want to install only a specific framework, you can pass the name of the framework @@ -60,5 +60,25 @@ Installation isaaclab.bat --install rl_games :: or "isaaclab.bat -i rl_games" - The valid options are ``all``, ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``, - and ``none``. If ``none`` is passed, then no learning frameworks will be installed. + To install only specific sub-packages, pass a comma-separated list of sub-package names. The available + sub-packages are: ``assets``, ``physx``, ``contrib``, ``mimic``, ``newton``, ``rl``, ``tasks``, + ``teleop``. For example, to install only the ``mimic`` and ``assets`` sub-packages: + + .. tab-set:: + :sync-group: os + + .. tab-item:: :icon:`fa-brands fa-linux` Linux + :sync: linux + + .. code:: bash + + ./isaaclab.sh --install physx,assets,rl,tasks # or "./isaaclab.sh -i physx,assets,rl,tasks" + + .. tab-item:: :icon:`fa-brands fa-windows` Windows + :sync: windows + + .. code:: batch + + isaaclab.bat --install physx,assets,rl,tasks :: or "isaaclab.bat -i physx,assets,rl,tasks" + + Pass ``none`` to install only the core ``isaaclab`` package without any sub-packages or RL frameworks. diff --git a/docs/source/setup/installation/include/src_clone_isaaclab.rst b/docs/source/setup/installation/include/src_clone_isaaclab.rst index 844cac2f3fd..3ef55579215 100644 --- a/docs/source/setup/installation/include/src_clone_isaaclab.rst +++ b/docs/source/setup/installation/include/src_clone_isaaclab.rst @@ -39,21 +39,36 @@ respectively that provides utilities to manage extensions. ./isaaclab.sh --help - usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab. - - optional arguments: - -h, --help Display the help content. - -i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'. - -f, --format Run pre-commit to format the code and check lints. - -p, --python Run the python executable provided by Isaac Sim or virtual environment (if active). - -s, --sim Run the simulator executable (isaac-sim.sh) provided by Isaac Sim. - -t, --test Run all python pytest tests. - -o, --docker Run the docker container helper script (docker/container.sh). - -v, --vscode Generate the VSCode settings file from template. - -d, --docs Build the documentation from source using sphinx. - -n, --new Create a new external project or internal task from template. - -c, --conda [NAME] Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'. - -u, --uv [NAME] Create the uv environment for Isaac Lab. Default name is 'env_isaaclab'. + usage: isaaclab.sh [-h] [-i [INSTALL]] [-f] [-p ...] [-s ...] [-t ...] [-o ...] [-v] [-d] [-n ...] [-c [CONDA]] [-u [UV]] + + Isaac Lab CLI + + options: + -h, --help show this help message and exit + -i [INSTALL], --install [INSTALL] + Install Isaac Lab sub-packages and RL frameworks. + Accepts a comma-separated list of sub-package names, one of the RL frameworks, or a special value. + + Sub-packages: assets, physx, contrib, mimic, newton, rl, tasks, teleop. + RL frameworks: rl_games, rsl_rl, sb3, skrl, robomimic. + + Passing an RL framework name installs all sub-packages + that framework. + + Special values: + - all - Install all extensions + all RL frameworks (default). + - none - Install only the core 'isaaclab' package. + - (-i or --install without value) - Install all extensions + all RL frameworks. + -f, --format Run pre-commit to format the code and check lints. + -p ..., --python ... Run the python executable provided by Isaac Sim or virtual environment (if active). + -s ..., --sim ... Run the simulator executable (isaac-sim.sh) provided by Isaac Sim. + -t ..., --test ... Run all python pytest tests. + -o ..., --docker ... Run the docker container helper script (docker/container.sh). + -v, --vscode Generate the VSCode settings file from template. + -d, --docs Build the documentation from source using sphinx. + -n ..., --new ... Create a new external project or internal task from template. + -c [CONDA], --conda [CONDA] + Create a new conda environment for Isaac Lab. Default name is 'env_isaaclab'. + -u [UV], --uv [UV] Create a new uv environment for Isaac Lab. Default name is 'env_isaaclab'. .. tab-item:: :icon:`fa-brands fa-windows` Windows :sync: windows @@ -62,17 +77,33 @@ respectively that provides utilities to manage extensions. isaaclab.bat --help - usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab. - - optional arguments: - -h, --help Display the help content. - -i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'. - -f, --format Run pre-commit to format the code and check lints. - -p, --python Run the python executable provided by Isaac Sim or virtual environment (if active). - -s, --sim Run the simulator executable (isaac-sim.bat) provided by Isaac Sim. - -t, --test Run all python pytest tests. - -v, --vscode Generate the VSCode settings file from template. - -d, --docs Build the documentation from source using sphinx. - -n, --new Create a new external project or internal task from template. - -c, --conda [NAME] Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'. - -u, --uv [NAME] Create the uv environment for Isaac Lab. Default name is 'env_isaaclab'. + usage: isaaclab.bat [-h] [-i [INSTALL]] [-f] [-p ...] [-s ...] [-t ...] [-o ...] [-v] [-d] [-n ...] [-c [CONDA]] [-u [UV]] + + Isaac Lab CLI + + options: + -h, --help show this help message and exit + -i [INSTALL], --install [INSTALL] + Install Isaac Lab sub-packages and RL frameworks. + Accepts a comma-separated list of sub-package names, one of the RL frameworks, or a special value. + + Sub-packages: assets, physx, contrib, mimic, newton, rl, tasks, teleop. + RL frameworks: rl_games, rsl_rl, sb3, skrl, robomimic. + + Passing an RL framework name installs all sub-packages + that framework. + + Special values: + - all - Install all extensions + all RL frameworks (default). + - none - Install only the core 'isaaclab' package. + - (-i or --install without value) - Install all extensions + all RL frameworks. + -f, --format Run pre-commit to format the code and check lints. + -p ..., --python ... Run the python executable provided by Isaac Sim or virtual environment (if active). + -s ..., --sim ... Run the simulator executable (isaac-sim.bat) provided by Isaac Sim. + -t ..., --test ... Run all python pytest tests. + -o ..., --docker ... Run the docker container helper script (docker/container.sh). + -v, --vscode Generate the VSCode settings file from template. + -d, --docs Build the documentation from source using sphinx. + -n ..., --new ... Create a new external project or internal task from template. + -c [CONDA], --conda [CONDA] + Create a new conda environment for Isaac Lab. Default name is 'env_isaaclab'. + -u [UV], --uv [UV] Create a new uv environment for Isaac Lab. Default name is 'env_isaaclab'. diff --git a/docs/source/setup/installation/include/src_python_virtual_env.rst b/docs/source/setup/installation/include/src_python_virtual_env.rst index 9f5b81ef359..3f66ac644f8 100644 --- a/docs/source/setup/installation/include/src_python_virtual_env.rst +++ b/docs/source/setup/installation/include/src_python_virtual_env.rst @@ -76,7 +76,7 @@ instead of *./isaaclab.sh -p* or *isaaclab.bat -p*. :: Activate environment conda activate env_isaaclab # or "conda activate my_env" - .. tab-item:: UV Environment (experimental) + .. tab-item:: UV Environment To install ``uv``, please follow the instructions `here `__. You can create the Isaac Lab environment using the following commands: diff --git a/docs/source/setup/installation/isaaclab_pip_installation.rst b/docs/source/setup/installation/isaaclab_pip_installation.rst index c9577c1307c..c35792bfcfd 100644 --- a/docs/source/setup/installation/isaaclab_pip_installation.rst +++ b/docs/source/setup/installation/isaaclab_pip_installation.rst @@ -17,19 +17,79 @@ To learn about how to set up your own project on top of Isaac Lab, please see :r .. include:: include/pip_python_virtual_env.rst -Installing dependencies -~~~~~~~~~~~~~~~~~~~~~~~ +Installing Isaac Lab +~~~~~~~~~~~~~~~~~~~~ -.. note:: +The ``isaaclab`` package provides optional extras to install Isaac Sim and individual +Isaac Lab sub-packages: - In case you used UV to create your virtual environment, please replace ``pip`` with ``uv pip`` - in the following commands. +.. list-table:: + :header-rows: 1 + :widths: 15 55 -- Install the Isaac Lab packages along with Isaac Sim: + * - Extra + - What it installs + * - ``isaacsim`` + - Isaac Sim (``isaacsim[all,extscache]==X.X.X``) from `pypi.nvidia.com `_ + * - ``assets`` + - ``isaaclab_assets`` + * - ``physx`` + - ``isaaclab_physx`` + * - ``contrib`` + - ``isaaclab_contrib`` + * - ``mimic`` + - ``isaaclab_mimic`` + * - ``newton`` + - ``isaaclab_newton`` + * - ``rl`` + - ``isaaclab_rl`` + * - ``tasks`` + - ``isaaclab_tasks`` + * - ``teleop`` + - ``isaaclab_teleop`` + * - ``all`` + - All of the above sub-packages (does **not** include ``isaacsim``) - .. code-block:: none +.. tab-set:: + + .. tab-item:: uv + + .. code-block:: bash + + # Isaac Lab only + uv pip install isaaclab # latest version + uv pip install isaaclab==3.0.0 # specific version + + # Isaac Lab + Isaac Sim + uv pip install "isaaclab[isaacsim]" + + # Isaac Lab + specific sub-package(s) + uv pip install "isaaclab[assets]" + uv pip install "isaaclab[rl,tasks]" - pip install isaaclab[isaacsim,all]==3.0.0 --extra-index-url https://pypi.nvidia.com + # Isaac Lab + Isaac Sim + all sub-packages + uv pip install "isaaclab[isaacsim,all]" + + .. tab-item:: pip + + .. code-block:: bash + + # Isaac Lab only + pip install isaaclab # latest version + pip install isaaclab==3.0.0 # specific version + + # Isaac Lab + Isaac Sim + pip install "isaaclab[isaacsim]" --extra-index-url https://pypi.nvidia.com + + # Isaac Lab + specific sub-package(s) + pip install "isaaclab[assets]" + pip install "isaaclab[rl,tasks]" + + # Isaac Lab + Isaac Sim + all Isaac Lab sub-packages + pip install "isaaclab[isaacsim,all]" --extra-index-url https://pypi.nvidia.com + +Installing dependencies +~~~~~~~~~~~~~~~~~~~~~~~ - Install a CUDA-enabled PyTorch 2.10.0 build that matches your system architecture: diff --git a/docs/source/setup/quickstart.rst b/docs/source/setup/quickstart.rst index 877f44cf036..f046cb8e4f0 100644 --- a/docs/source/setup/quickstart.rst +++ b/docs/source/setup/quickstart.rst @@ -40,7 +40,7 @@ To begin, we first define our virtual environment. # activate the virtual environment conda activate env_isaaclab - .. tab-item:: uv (experimental) + .. tab-item:: uv .. tab-set:: :sync-group: os diff --git a/pyproject.toml b/pyproject.toml index 050b2dee5d4..7f77a42ddf2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -140,3 +140,9 @@ ignore-words-list = "haa,slq,collapsable,buss,reacher,thirdparty" markers = [ "isaacsim_ci: mark test to run in isaacsim ci", ] + +# Add pypi.nvidia.com so that `uv pip install isaaclab[isaacsim]` works without --extra-index-url. +# Pip still needs "--extra-index-url https://pypi.nvidia.com". +[[tool.uv.index]] +url = "https://pypi.nvidia.com" +explicit = false diff --git a/source/isaaclab/isaaclab/cli/__init__.py b/source/isaaclab/isaaclab/cli/__init__.py index 59f961be942..a10a9d812b5 100644 --- a/source/isaaclab/isaaclab/cli/__init__.py +++ b/source/isaaclab/isaaclab/cli/__init__.py @@ -35,8 +35,20 @@ def cli() -> None: "--install", nargs="?", const="all", - help="Install the extensions inside Isaac Lab and learning frameworks as extra dependencies.\n" - + "Can be used in any active conda/uv environment. Default is 'all'.", + help=( + "Install Isaac Lab sub-packages and RL frameworks.\n" + "Accepts a comma-separated list of sub-package names, one of the RL frameworks, or a special value.\n" + "\n" + "Sub-packages: assets, physx, contrib, mimic, newton, rl, tasks, teleop.\n" + "RL frameworks: rl_games, rsl_rl, sb3, skrl, robomimic.\n" + "\n" + "Passing an RL framework name installs all sub-packages + that framework.\n" + "\n" + "Special values:\n" + "- all - Install all sub-packages + all RL frameworks (default).\n" + "- none - Install only the core 'isaaclab' package.\n" + "- (-i or --install without value) - Install all sub-packages + all RL frameworks.\n" + ), ) parser.add_argument( "-f", diff --git a/source/isaaclab/isaaclab/cli/commands/install.py b/source/isaaclab/isaaclab/cli/commands/install.py index d78082998cd..b509b13f920 100644 --- a/source/isaaclab/isaaclab/cli/commands/install.py +++ b/source/isaaclab/isaaclab/cli/commands/install.py @@ -121,8 +121,25 @@ def _ensure_cuda_torch() -> None: ) -def _install_isaaclab_extensions() -> None: - """check if input directory is a python extension and install the module""" +# Valid sub-package names that can be passed to --install. +# Each sub-package maps to a source directory named "isaaclab_" under source/. +VALID_ISAACLAB_SUBPACKAGES: set[str] = {"assets", "physx", "contrib", "mimic", "newton", "rl", "tasks", "teleop"} + +# RL framework names accepted. +# Passing one of these installs all extensions + that framework. +VALID_RL_FRAMEWORKS: set[str] = {"rl_games", "rsl_rl", "sb3", "skrl", "robomimic"} + + +def _install_isaaclab_extensions(extensions: list[str] | None = None) -> None: + """Install Isaac Lab extensions from the source directory. + + Scans ``source/`` for sub-directories that contain a ``setup.py`` and + installs each one as an editable pip package. + + Args: + extensions: Optional, list of source directory names to install + If ``None`` is provided, every extension found under ``source/`` is installed. + """ python_exe = extract_python_exe() source_dir = ISAACLAB_ROOT / "source" @@ -135,6 +152,9 @@ def _install_isaaclab_extensions() -> None: # source directory for item in source_dir.iterdir(): if item.is_dir() and (item / "setup.py").exists(): + # Skip extensions not in the requested list. + if extensions is not None and item.name not in extensions: + continue print_info(f"Installing extension: {item.name}") # If the directory contains setup.py then install the python module. run_command( @@ -192,12 +212,20 @@ def _install_extra_frameworks(framework_name: str = "all") -> None: def command_install(install_type: str = "all") -> None: - """ - Install stuff + """Install Isaac Lab extensions and optional sub-packages. Args: - install_type (str): The RL framework to install ('all', 'none', or specific name). + install_type: Comma-separated list of extras to install, or one of the + special values ``"all"`` / ``"none"``. Extra names match the keys + in ``source/isaaclab/setup.py``'s ``extras_require``: + * ``"all"`` (default) — install every extension found under + ``source/``, plus all RL frameworks. + * ``"none"`` — install only the "core" ``isaaclab`` package and skip + RL frameworks. + * Comma-separated extras, e.g. ``"mimic,assets"`` — install + only the "core" ``isaaclab`` package plus the listed sub-packages. """ + # Install system dependencies first. _install_system_deps() @@ -213,6 +241,32 @@ def command_install(install_type: str = "all") -> None: print_info(f"Python executable: {python_exe}") + # Decide which source directories (source/isaaclab/*) to install. + # "all" : install everything + all RL frameworks + # "none" : core isaaclab only, no RL frameworks + # RL framework : install everything + only that RL framework (e.g. "skrl") + # "a,b" : core + selected sub-package directories, no RL frameworks + if install_type == "all": + extensions = None + framework_type = "all" + elif install_type == "none": + extensions = ["isaaclab"] + framework_type = "none" + elif install_type in VALID_RL_FRAMEWORKS: + # Single RL framework name: install all extensions + only that framework. + extensions = None + framework_type = install_type + else: + # Parse comma-separated sub-package names into source directory names. + extensions = ["isaaclab"] # core is always required + for name in (s.strip() for s in install_type.split(",") if s.strip()): + if name in VALID_ISAACLAB_SUBPACKAGES: + extensions.append(f"isaaclab_{name}") + else: + valid = sorted(VALID_ISAACLAB_SUBPACKAGES) + sorted(VALID_RL_FRAMEWORKS) + print_warning(f"Unknown sub-package '{name}'. Valid values: {', '.join(valid)}. Skipping.") + framework_type = "none" # RL frameworks not applied in selective mode + # if on ARM arch, temporarily clear LD_PRELOAD # LD_PRELOAD is restored below, after installation saved_ld_preload = None @@ -229,11 +283,11 @@ def command_install(install_type: str = "all") -> None: _ensure_cuda_torch() # Install the python modules for the extensions in Isaac Lab. - _install_isaaclab_extensions() + _install_isaaclab_extensions(extensions) # Install the python packages for supported reinforcement learning frameworks. print_info("Installing extra requirements such as learning frameworks...") - _install_extra_frameworks(install_type) + _install_extra_frameworks(framework_type) # In some rare cases, torch might not be installed properly by setup.py, add one more check here. # Can prevent that from happening. diff --git a/source/isaaclab/setup.py b/source/isaaclab/setup.py index 06fca3a4b85..46884a60400 100644 --- a/source/isaaclab/setup.py +++ b/source/isaaclab/setup.py @@ -50,7 +50,7 @@ "flaky", "packaging", # visualizers - "newton @ git+https://github.com/newton-physics/newton.git@35657fc", + "newton @ git+https://github.com/newton-physics/newton.git@v0.2.3", "imgui-bundle>=1.92.5", "rerun-sdk>=0.29.0", # Required by pydantic-core/imgui_bundle on Python 3.12 (Sentinel symbol). @@ -75,6 +75,31 @@ PYTORCH_INDEX_URL = ["https://download.pytorch.org/whl/cu128"] +# Isaac Lab subpackages + Isaac Sim +EXTRAS_REQUIRE = { + "isaacsim": ["isaacsim[all,extscache]==5.1.0"], + # Individual Isaac Lab sub-packages + "assets": ["isaaclab_assets"], + "physx": ["isaaclab_physx"], + "contrib": ["isaaclab_contrib"], + "mimic": ["isaaclab_mimic"], + "newton": ["isaaclab_newton"], + "rl": ["isaaclab_rl"], + "tasks": ["isaaclab_tasks"], + "teleop": ["isaaclab_teleop"], + # Convenience: all sub-packages (does not include isaacsim) + "all": [ + "isaaclab_assets", + "isaaclab_physx", + "isaaclab_contrib", + "isaaclab_mimic", + "isaaclab_newton", + "isaaclab_rl", + "isaaclab_tasks", + "isaaclab_teleop", + ], +} + # Installation operation setup( name="isaaclab", @@ -88,6 +113,7 @@ include_package_data=True, python_requires=">=3.10", install_requires=INSTALL_REQUIRES, + extras_require=EXTRAS_REQUIRE, dependency_links=PYTORCH_INDEX_URL, packages=["isaaclab"], classifiers=[ diff --git a/source/isaaclab_newton/setup.py b/source/isaaclab_newton/setup.py index 2e1e422391a..c6f91d102c7 100644 --- a/source/isaaclab_newton/setup.py +++ b/source/isaaclab_newton/setup.py @@ -22,7 +22,7 @@ # newton "mujoco==3.5.0", "mujoco-warp @ git+https://github.com/google-deepmind/mujoco_warp.git@7bb099c082d50803fd63bfe57217025d9f5cd2df", - "newton @ git+https://github.com/newton-physics/newton.git@c2c8588602951238ce07e34edaf983afccf23b5f", + "newton @ git+https://github.com/newton-physics/newton.git@v0.2.3", "PyOpenGL-accelerate==3.1.10", ]