Container images

Container images#

Each 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 container lifecycle.

Choosing an image#

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.

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:

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:

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:

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:

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:

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 Running Isaac Lab in 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.