.. _docker-images: Container images ================ Each :ref:`profile ` builds a different image. They differ in what simulation and rendering stack they carry, which decides how large they are and what they can run. This page describes the images themselves; to build or run one, name its profile in the :ref:`container lifecycle `. Choosing an image ----------------- .. list-table:: :header-rows: 1 :widths: 12 40 48 * - Profile - Contains - Use it when * - ``base`` - Isaac Lab on the NVIDIA Isaac Sim image, with Kit and RTX rendering - You want the default environment, GUI rendering, or anything that needs Isaac Sim * - ``ros2`` - The ``base`` image plus ROS 2 Humble - You are bridging Isaac Lab to ROS 2 nodes * - ``kitless`` - Ubuntu 24.04, Python 3.12, Newton and OVPhysX physics, OVRTX rendering, four RL libraries - You are training with Newton and want the smallest image; also the only one with no Isaac Sim EULA Base image ---------- ``Dockerfile.base`` overlays Isaac Lab's dependencies onto the Isaac Sim container, so it inherits Kit, RTX rendering, and the Isaac Sim asset pipeline. The Isaac Sim version it builds against is set by ``ISAACSIM_VERSION`` in ``.env.base``; the other variables in that file control paths inside the container. ROS 2 image ----------- ``Dockerfile.ros2`` installs ROS 2 Humble from an `apt package`_ and sources it in the runtime user's ``.bashrc``. ``ROS2_APT_PACKAGE`` in ``.env.ros2`` selects the package set, defaulting to ``ros-base``. The image defaults to the ``FastRTPS`` middleware; ``CycloneDDS`` is also supported, and both can be `tuned`_ through their ``.xml`` files under ``docker/.ros``. See `various middleware`_ for the trade-offs. .. dropdown:: Parameters in .env.ros2 :icon: code .. literalinclude:: ../../../../docker/.env.ros2 :language: bash Kit-less image -------------- The kit-less image drops Isaac Sim entirely and builds on Ubuntu 24.04 with Python 3.12. It carries Newton physics, OVPhysX physics, OVRTX rendering, and the four core RL frameworks: RL Games, RSL-RL, Stable-Baselines3, and SKRL. The ``newton_gl``, ``newton_rtx``, ``viser``, and ``rerun`` visualizers are included. Use ``--viz newton_gl`` for local visualization with a display available in the container. ``--viz newton_gl`` selects the OpenGL rasterizer; ``--viz newton_rtx`` selects the OVRTX path tracer. Both can render offscreen without Isaac Sim. Windowed use additionally needs a display server accessible inside the container. The deprecated ``--viz newton`` alias selects GL; it does not choose between GL and RTX automatically. Rendering needs NVIDIA graphics driver capabilities in addition to compute. For direct ``docker run`` commands, pass ``--gpus all -e NVIDIA_DRIVER_CAPABILITIES=all``. The NVIDIA Container Toolkit exposes the host driver; avoid mounting a second copy of its Vulkan ICD. If multiple drivers are discovered, select the NVIDIA ICD available inside the container with ``VK_DRIVER_FILES`` (for example, ``/etc/vulkan/icd.d/nvidia_icd.json``). No visualizer is selected by default, so training runs headless unless you ask for one. The ``kit`` visualizer is the exception: it comes from Omniverse Kit, which this image does not contain. Unlike the other two, it bind-mounts ``apps`` in addition to ``source``, ``scripts``, ``tools``, and ``docs``, and it keeps a uv cache and a Warp cache of its own. You do not have to build it locally. It is published alongside each Isaac Lab release in the same registry repository, distinguished by a ``-kitless`` tag suffix: .. code:: bash docker pull nvcr.io/nvidia/isaac-lab:3.0.0-rc1-kitless Running it directly, outside the Compose workflow, is a convenient way to verify the image and your NVIDIA Container Toolkit setup. ``--interactive`` and ``--tty`` keep the container's shell alive so that several commands can share it: .. code:: bash docker run --name isaac-lab-kitless --detach --interactive --tty --gpus all --network host \ -e NVIDIA_DRIVER_CAPABILITIES=all \ nvcr.io/nvidia/isaac-lab:3.0.0-rc1-kitless docker exec isaac-lab-kitless \ isaaclab train --rl_library rsl_rl --task Isaac-Cartpole-Direct \ --num_envs 16 presets=newton_mjwarp --max_iterations 5 Replay in a browser with: .. code:: bash docker exec --interactive --tty isaac-lab-kitless \ isaaclab play --rl_library rsl_rl --task Isaac-Cartpole-Direct \ --num_envs 16 presets=newton_mjwarp --checkpoint latest --viz viser Viser is reachable through the host network without forwarding a desktop display. Stop playback with ``Ctrl+C`` without stopping the container. To build the image from the checkout instead of pulling it, run ``docker build --file docker/Dockerfile.kitless --tag isaac-lab-kitless .``. Only ``linux/amd64`` images are published. The Dockerfile itself is architecture-agnostic, but the published manifest is limited to the architecture that is validated in CI. Pre-built image from NGC ------------------------ A minimal pre-built container carries a small set of Isaac Sim and Omniverse dependencies with Isaac Lab already built in, under ``/workspace/isaaclab``. The example below runs without a forwarded desktop display. Choose the image profile for the physics and rendering stack you need, and configure graphics access separately when rendering. .. note:: Use an explicit published version tag for reproducible runs. The examples below use ``3.0.0-rc1``; the corresponding kit-less image uses ``3.0.0-rc1-kitless``. .. attention:: Images from 3.0.0-beta2 onward run as a **non-root** user, so those bind-mount directories must be writable by uid/gid 1000. Docker creates any missing one as ``root``, which the runtime user cannot write to, producing errors such as ``PermissionError: [Errno 13] Permission denied: '/root/.local/share/ov/data/exts'``. Create them first: .. code:: bash mkdir -p ~/docker/isaac-sim/{cache/kit,cache/ov,cache/pip,cache/glcache,cache/computecache,logs,data,documents} sudo chown -R 1000:1000 ~/docker/isaac-sim Because it is run outside Compose, the Isaac Sim cache directories have to be mounted by hand, otherwise every start recompiles shaders: .. code:: bash docker run --name isaac-lab --entrypoint bash -it --gpus all -e "ACCEPT_EULA=Y" --rm --network=host \ -e "PRIVACY_CONSENT=Y" \ -v ~/docker/isaac-sim/cache/kit:/isaac-sim/kit/cache:rw \ -v ~/docker/isaac-sim/cache/ov:/root/.cache/ov:rw \ -v ~/docker/isaac-sim/cache/pip:/root/.cache/pip:rw \ -v ~/docker/isaac-sim/cache/glcache:/root/.cache/nvidia/GLCache:rw \ -v ~/docker/isaac-sim/cache/computecache:/root/.nv/ComputeCache:rw \ -v ~/docker/isaac-sim/logs:/root/.nvidia-omniverse/logs:rw \ -v ~/docker/isaac-sim/data:/root/.local/share/ov/data:rw \ -v ~/docker/isaac-sim/documents:/root/Documents:rw \ nvcr.io/nvidia/isaac-lab:3.0.0-rc1 For windowed use, follow the X11 setup in :ref:`deployment-docker`; the container needs access to the host display and matching authorization. For direct ``docker run`` use, add ``-e DISPLAY -e XAUTHORITY=/tmp/isaaclab.xauth`` and the mounts ``-v /tmp/.X11-unix:/tmp/.X11-unix:rw`` and ``-v "${XAUTHORITY:-$HOME/.Xauthority}":/tmp/isaaclab.xauth:ro`` to the command above. The host authority file must exist and be readable by the container user. Offscreen Newton rendering does not require X11. Follow the graphics-driver requirements above for GL or RTX. Runtime user ------------ The base, ROS 2, cuRobo, and kit-less images all run as a non-root user with uid/gid 1000, which keeps bind-mounted workspaces writable on GitHub runners. When running one of these images directly with ``docker run`` from a host account whose uid differs, pass ``--user "$(id -u):1000"`` so that new files on bind mounts belong to your host user while the runtime home stays accessible. Python interpreter ------------------ Every image installs from ``uv.lock`` into a Python 3.12 virtual environment at ``/opt/isaaclab-venv``. On the Isaac Sim-based images the environment is built on Isaac Sim's own interpreter, and Isaac Sim itself stays outside it, reached through the ``_isaac_sim`` symlink; ``isaaclab.sh`` puts it on the path. In either case ``python`` on the container's ``PATH`` resolves to the right one, so scripts are run the same way regardless of image. .. _`apt package`: https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html#install-ros-2-packages .. _`various middleware`: https://docs.ros.org/en/humble/How-To-Guides/Working-with-multiple-RMW-implementations.html .. _`tuned`: https://docs.ros.org/en/foxy/How-To-Guides/DDS-tuning.html