[Docker] Install the Docker images from uv.lock (isaac-sim#7405)

## Summary

Docker images stop mutating Isaac Sim's shipped Python environment: the
previous build
replaced **41** of its packages, this one replaces **0**. All three
images install from
`uv.lock`, so builds are reproducible and
`[tool.uv].override-dependencies` apply.

# Description

The lock is the only path that applies
`[tool.uv].override-dependencies`, which pip cannot
read. The change is contained to the Docker build; `isaaclab.sh
--install` is unchanged.

- **Isaac Sim image** — `uv sync` resolves into a venv at
`/opt/isaaclab-venv`, built on Kit's
own interpreter. Isaac Sim is untouched, still reached through the
existing `_isaac_sim`
symlink, and `isaaclab.sh` sources `setup_python_env.sh` so `import
isaacsim` keeps working.
- **Kit-less image** — `uv sync` replaces the pip-style install,
retiring the duplicated
  `tools/wheel_builder/uv-overrides.txt`.
- **cuRobo image** — same migration. Because Isaac Sim's site-packages
is no longer touched,
the image stops deleting the prebundled torch, re-bootstrapping `pip`
with `get-pip.py`, and
  uninstalling `quadprog`. cuRobo is still built from its pinned commit.
- **No new extras** — the images use the ones that already exist.
`teleop` no longer bundles
the `isaacsim` wheel, so environments that already provide Kit do not
install a second,
version-mismatched copy; installs that need it use `--extra
teleop,isaacsim`, and the docs
say so wherever XR teleop appears (agreed with the teleop owner). `test`
is now the test
suite alone and `dev` adds the documentation toolchain, so the images
can install `test`
without shipping Sphinx and its GPL-3.0-or-later `docutils`, which the
Docker licence gate
  rejects.

- **Image invariant test** — the images install with `uv sync`, which
never runs
`command_install`'s dangling-symlink guard, so isaac-sim#6329's protection would
have been lost. A
post-build step asserts no prebundled package lost its `__init__.py`,
bound to the digest
just built. It has already caught a real regression on a dependent
branch.
- **Removed** the `quadprog` uninstall (absent from the lock), the
`toml` install
(`install_deps.py` now uses stdlib `tomllib`), and the `imageio-ffmpeg`
uninstall
  (excluded during the sync instead).

Newton resolves to 1.5.0 from the lock's pinned commit where the pip
path floated to
`release-1.5` HEAD (1.5.1); regenerating `uv.lock` is the lever if a
newer commit is needed.

`uv.lock` is regenerated with uv 0.9.25, the version the images pin.
Newer uv renormalises
environment markers and rewrites ~2200 lines with no semantic change.

## Type of change

- New feature (non-breaking change which adds functionality)

## Release backport

- [ ] <!-- backport-active-release --> Backport this pull request to the
active release branch after it merges into `develop`

## 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 — a post-build image-invariant test, plus building all
three images and diffing their package sets against the previous build
- [x] I have added a changelog fragment under
`source/<pkg>/changelog.d/` for every touched package
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

---------

Co-authored-by: ooctipus <zhengyuz@nvidia.com>

Author: hujc7

.dockerignore

@@ -21,6 +21,8 @@ docker/.container.cfg
 recordings/
 # ignore __pycache__
 **/__pycache__/
+**/.pytest_cache/
+**/.ruff_cache/
 **/*.egg-info/
 # ignore isaac sim symlink
 _isaac_sim

.github/actions/run-tests/run_tests.sh

@@ -357,13 +357,19 @@ run_tests() {
       fi
       if [ -n \"\${TEST_EXTRA_UV_PACKAGES:-}\" ]; then
         echo \"Installing extra packages with uv: \${TEST_EXTRA_UV_PACKAGES}\"
-        # isaaclab.sh prints an informational line before command output, and pip
-        # installs scripts into the user base when Isaac Sim site-packages is read-only.
-        isaac_python=\"\$(./isaaclab.sh -p -c 'import sys; print(sys.executable)' | tail -n 1)\"
-        isaac_user_site=\"\$(./isaaclab.sh -p -c 'import site; print(site.getusersitepackages())' | tail -n 1)\"
-        uv_executable=\"\$(./isaaclab.sh -p -c 'import pathlib, site; print(pathlib.Path(site.getuserbase()) / \"bin\" / \"uv\")' | tail -n 1)\"
-        if [ ! -x \"\${uv_executable}\" ]; then
-          bash /with-python-package-retries.sh ./isaaclab.sh -p -m pip install uv
+        # isaaclab.sh prints an [INFO] banner on stdout around the command output, so the
+        # banner is filtered rather than positionally skipped.
+        isaac_python=\"\$(./isaaclab.sh -p -c 'import sys; print(sys.executable)' | grep -v '^\[INFO\]' | tail -n 1)\"
+        isaac_user_site=\"\$(./isaaclab.sh -p -c 'import site; print(site.getusersitepackages())' | grep -v '^\[INFO\]' | tail -n 1)\"
+        # The image ships uv on PATH. Fall back to the user base only for images that do
+        # not: pip installs into the venv, not the user base, when the interpreter is a venv,
+        # so the user-base path is never created there.
+        uv_executable=\"\$(command -v uv || true)\"
+        if [ -z \"\${uv_executable}\" ]; then
+          uv_executable=\"\$(./isaaclab.sh -p -c 'import pathlib, site; print(pathlib.Path(site.getuserbase()) / \"bin\" / \"uv\")' | grep -v '^\[INFO\]' | tail -n 1)\"
+          if [ ! -x \"\${uv_executable}\" ]; then
+            bash /with-python-package-retries.sh ./isaaclab.sh -p -m pip install uv
+          fi
         fi
         bash /with-python-package-retries.sh \"\${uv_executable}\" pip install --python \"\${isaac_python}\" --target \"\${isaac_user_site}\" \${TEST_EXTRA_UV_PACKAGES}
         # Isaac Sim puts bundled packages ahead of the user site. Overlay only

.github/workflows/build.yaml

@@ -46,7 +46,7 @@
 #      -e TEST_FILTER_PATTERN="isaaclab_physx" \
 #      -e TEST_INCLUDE_FILES="test_rigid_object_collection.py" \
 #      -v "$PWD":/workspace/isaaclab isaac-lab-base:latest \
-#      -c 'cd /workspace/isaaclab && /isaac-sim/python.sh -m pytest tools -v'
+#      -c 'cd /workspace/isaaclab && ./isaaclab.sh -p -m pytest tools -v'
 #
 # Remember to REVERT all temporary changes before merging!
 # =============================================================================
@@ -169,6 +169,25 @@ jobs:
         echo "ci_image_tag=isaac-lab-ci:${sanitized_ref}-${SHA}" >> "$GITHUB_OUTPUT"
         echo "CI image tag: isaac-lab-ci:${sanitized_ref}-${SHA}"
 
+  test-dockerfile-contract:
+    name: dockerfile-contract
+    # Static analysis of the Dockerfile text: no image, no GPU, no Isaac Sim.
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+
+    - name: Run Dockerfile contract tests
+      shell: bash
+      run: |
+        set -euo pipefail
+        uv run --no-project --with pytest \
+          python -m pytest -q docker/test/test_dockerfile_nonroot.py
+
   #region build jobs
   build:
     name: Build Base Docker Image
@@ -182,6 +201,12 @@ jobs:
         fetch-depth: 1
         lfs: true
 
+    # The GPU runners have no uv on PATH; the invariant check below needs it.
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+
     - name: Build and push to ECR
       uses: ./.github/actions/ecr-build-push-pull
       with:
@@ -191,6 +216,20 @@ jobs:
         dockerfile-path: docker/Dockerfile.base
         cache-tag: cache-base
 
+    # #6329 aborts the pip install when it strands a prebundled package's __init__.py
+    # (nvbugs 6343978: 14 Isaac Sim extensions fail to load). The images install with
+    # ``uv sync``, which never runs that guard, so assert the same invariant on the image.
+    - name: Verify image invariants
+      shell: bash
+      env:
+        IMAGE_TAG: ${{ needs.config.outputs.ci_image_tag }}
+      run: |
+        set -euo pipefail
+        IMAGE_DIGEST="$(docker image inspect --format '{{.Id}}' "${IMAGE_TAG}")"
+        export IMAGE_DIGEST
+        uv run --no-project --with pytest \
+          python -m pytest -q docker/test/test_image_invariants.py
+
   build-curobo:
     name: Build cuRobo Docker Image
     runs-on: [self-hosted, gpu]
@@ -661,16 +700,6 @@ jobs:
     # Folded from the former standalone verify-base-non-root job: reuses the
     # base image already pulled by run-package-tests to keep the regression
     # check without burning a separate runner.
-    - name: Run Dockerfile non-root regression test
-      shell: bash
-      run: |
-        set -euo pipefail
-        docker run --rm \
-          -v "$PWD":/workspace/isaaclab \
-          --entrypoint bash \
-          "${{ needs.config.outputs.ci_image_tag }}" \
-          -lc 'cd /workspace/isaaclab && /isaac-sim/python.sh -m pytest docker/test/test_dockerfile_nonroot.py -q'
-
     - name: Verify Base runtime user is non-root
       shell: bash
       run: |
@@ -711,16 +740,6 @@ jobs:
     # Folded from the former standalone verify-curobo-non-root job: reuses
     # the curobo image already pulled by run-package-tests to keep the
     # regression check without burning a separate runner.
-    - name: Run Dockerfile non-root regression test
-      shell: bash
-      run: |
-        set -euo pipefail
-        docker run --rm \
-          -v "$PWD":/workspace/isaaclab \
-          --entrypoint bash \
-          "${{ needs.config.outputs.ci_image_tag }}-curobo" \
-          -lc 'cd /workspace/isaaclab && /isaac-sim/python.sh -m pytest docker/test/test_dockerfile_nonroot.py -q'
-
     - name: Verify cuRobo runtime user is non-root
       shell: bash
       run: |

.github/workflows/docs.yaml

@@ -66,7 +66,7 @@ jobs:
 
     - name: Install docs dependencies
       run: |
-        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" uv sync --extra test
+        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" uv sync --extra dev
         echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
 
     - name: Build current version docs
@@ -98,7 +98,7 @@ jobs:
 
     - name: Install docs dependencies
       run: |
-        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" uv sync --extra test
+        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" uv sync --extra dev
         echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
 
     - name: Generate multi-version docs

.github/workflows/license-check.yaml

@@ -62,7 +62,7 @@ jobs:
         ISAACSIM_ACCEPT_EULA: YES
       run: |
         bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" \
-          uv sync --extra all --extra isaacsim --extra test --extra rlinf --extra mimic
+          uv sync --extra all --extra isaacsim --extra dev --extra rlinf --extra mimic
         # ``[tool.uv.pip] prerelease = "allow"`` lets unpinned tools float onto
         # prereleases. pip-licenses 6.0.0a1 reports an empty License where 5.x reports
         # ``UNKNOWN``, which license-exceptions.json keys on, and joins multi-license

docker/Dockerfile.base

@@ -9,6 +9,10 @@
 # Base image
 ARG ISAACSIM_BASE_IMAGE_ARG=nvcr.io/nvidia/isaac-sim
 ARG ISAACSIM_VERSION_ARG=6.0.0
+
+# uv, pinned by digest. Declared after the ARGs so those stay global for the base FROM.
+FROM ghcr.io/astral-sh/uv:0.12.9@sha256:8b940d3a9d65bed080436972241af2e21c84b5e8c9193f7014ed71479ee795ff AS uv
+
 FROM ${ISAACSIM_BASE_IMAGE_ARG}:${ISAACSIM_VERSION_ARG} AS base
 ARG ISAACSIM_VERSION_ARG
 ENV ISAACSIM_VERSION=${ISAACSIM_VERSION_ARG}
@@ -32,10 +36,19 @@ ARG DOCKER_USER_HOME_ARG
 ENV DOCKER_USER_HOME=${DOCKER_USER_HOME_ARG}
 ENV HOME=${DOCKER_USER_HOME}
 
-# Set environment variables
+# Locale and apt behaviour.
 ENV LANG=C.UTF-8
 ENV DEBIAN_FRONTEND=noninteractive
-ENV PIP_RETRIES=12
+
+# uv. Dependencies resolve from uv.lock into this venv instead of Isaac Sim's own
+# site-packages; isaaclab.sh sources setup_python_env.sh so ``isaacsim`` stays importable.
+# uv is pinned to Kit's interpreter: ``python-preference = "only-managed"`` would otherwise
+# download a CPython that cannot load Kit's extension modules.
+ARG VENV_PATH_ARG=/opt/isaaclab-venv
+ENV VIRTUAL_ENV=${VENV_PATH_ARG}
+ENV UV_PROJECT_ENVIRONMENT=${VENV_PATH_ARG}
+ENV UV_PYTHON=${ISAACSIM_ROOT_PATH_ARG}/kit/python/bin/python3
+ENV UV_PYTHON_PREFERENCE=only-system
 ENV UV_HTTP_RETRIES=12
 
 # Base image may end with a non-root user; switch to root for system-level
@@ -71,27 +84,24 @@ RUN if [ "$(dpkg --print-architecture)" = "arm64" ]; then \
 
 # copy files necessary for installing Isaac Lab and its dependencies
 # this way we minimize the chance of cache invalidation on file edits
-COPY ../isaaclab.* ../environment.yml ../pyproject.toml ${ISAACLAB_PATH}/
+COPY --from=uv /uv /uvx /usr/local/bin/
+COPY ../isaaclab.* ../environment.yml ../pyproject.toml ../uv.lock ${ISAACLAB_PATH}/
 COPY ../tools/ ${ISAACLAB_PATH}/tools/
-COPY ../source/ ${ISAACLAB_PATH}/source/
-
-# Fix the line endings for the shell scripts (Windows git may add \r)
-RUN find ${ISAACLAB_PATH} -type f -name "*.sh" -exec sed -i 's/\r$//' {} +
-
-# Ensure isaaclab.sh has execute permissions
-RUN chmod +x ${ISAACLAB_PATH}/isaaclab.sh
 
 # Set up a symbolic link between the installed Isaac Sim root folder and _isaac_sim in the Isaac Lab directory
 RUN ln -sf ${ISAACSIM_ROOT_PATH} ${ISAACLAB_PATH}/_isaac_sim
 
-# Install toml (used by tools/install_deps.py) and pytest (needed to run
-# in-container tests; moved to optional [test] extra in pyproject.toml)
-RUN ${ISAACLAB_PATH}/isaaclab.sh -p -m pip install toml pytest
+# Created before the venv so every install layer can set ownership as it writes, instead of
+# a recursive chown afterwards: on overlayfs a chown copies up every file it touches, which
+# costs both build time and a duplicate of the venv in the image.
+# The uid/gid 1000 match GitHub runner bind mounts used by Docker tests.
+# --non-unique is required because some base image revisions already carry
+# another user or group at uid/gid 1000.
+RUN groupadd --non-unique --gid 1000 isaaclab \
+ && useradd --non-unique --uid 1000 --gid 1000 -M -l -s /bin/bash -d ${DOCKER_USER_HOME} isaaclab
 
-# Install apt dependencies for extensions that declare them in their extension.toml,
-RUN ${ISAACLAB_PATH}/isaaclab.sh -p ${ISAACLAB_PATH}/tools/install_deps.py apt ${ISAACLAB_PATH}/source && \
-    apt-get -y autoremove && apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
+# Created up front so the install steps below resolve into it.
+RUN uv venv --seed "${VIRTUAL_ENV}"
 
 # for singularity usage, have to create the directories that will binded
 RUN mkdir -p ${ISAACSIM_ROOT_PATH}/kit/cache && \
@@ -113,41 +123,79 @@ RUN touch /bin/nvidia-smi && \
     mkdir -p /var/run/nvidia-persistenced && \
     touch /var/run/nvidia-persistenced/socket
 
-# robomimic declares imageio-ffmpeg for optional video helpers. Keep its
-# bundled FFmpeg binary out of the distributed image and let users who
-# enable video recording install MoviePy and its video backend explicitly.
-RUN --mount=type=cache,target=${DOCKER_USER_HOME}/.cache/pip \
-    ${ISAACLAB_PATH}/isaaclab.sh --install && \
-    ${ISAACLAB_PATH}/isaaclab.sh -p -m pip uninstall -y imageio-ffmpeg
+# Workspace manifests only: ``uv sync --no-install-workspace`` needs every member's
+# pyproject.toml to build an installation plan, but not their sources. Resolving the ~240
+# third-party packages here means a source edit re-runs only the workspace install below.
+COPY --parents ../source/*/pyproject.toml ${ISAACLAB_PATH}/
+
+# The image's package set. Kit ships in the base image, so the teleop stack comes without the
+# ``isaacsim`` wheel; ``teleop`` itself is left exactly as tuned.
+ARG IMAGE_EXTRAS="--extra sb3 --extra skrl --extra rl-games --extra rsl-rl --extra viser --extra rerun --extra mimic --extra teleop --extra test"
 
-# HACK: Remove install of quadprog dependency
-RUN ${ISAACLAB_PATH}/isaaclab.sh -p -m pip uninstall -y quadprog
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    cd ${ISAACLAB_PATH} && \
+    uv sync --frozen --inexact ${IMAGE_EXTRAS} \
+      --no-install-workspace --no-install-package imageio-ffmpeg && \
+    chown -R isaaclab:isaaclab ${VIRTUAL_ENV} && \
+    chmod -R a+rwX ${VIRTUAL_ENV}/lib ${VIRTUAL_ENV}/bin
+
+COPY ../source/ ${ISAACLAB_PATH}/source/
+
+# Fix the line endings for the shell scripts (Windows git may add \r), then restore the
+# launcher's mode; one layer because both walk the tree the COPY above just wrote. ``sed -i``
+# rewrites the file under the build umask, so an explicit 755 keeps it runnable by a
+# container started with a uid other than the image's own.
+RUN find ${ISAACLAB_PATH} -type f -name "*.sh" -exec sed -i 's/\r$//' {} + \
+ && chmod 755 ${ISAACLAB_PATH}/isaaclab.sh
+
+# Install apt dependencies for extensions that declare them in their extension.toml,
+RUN ${ISAACLAB_PATH}/isaaclab.sh -p ${ISAACLAB_PATH}/tools/install_deps.py apt ${ISAACLAB_PATH}/source && \
+    apt-get -y autoremove && apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# robomimic and moviepy declare imageio-ffmpeg for optional video helpers. Its bundled
+# FFmpeg binary stays out of the distributed image; users who enable video recording install
+# MoviePy and its video backend explicitly.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    cd ${ISAACLAB_PATH} && \
+    uv sync --frozen --inexact ${IMAGE_EXTRAS} \
+      --no-install-package imageio-ffmpeg && \
+    find ${VIRTUAL_ENV} \! -user isaaclab \
+      -exec chown isaaclab:isaaclab {} + -exec chmod a+rwX {} +
+
+# Isaac Sim's prebundled packages sit on PYTHONPATH ahead of the venv for launch paths that
+# never import isaaclab (``runheadless.sh``, ``isaac-sim.streaming.sh``), so its torch would
+# shadow the venv's and load a libtorch_cuda.so needing an NCCL symbol the bundled NCCL does
+# not export (nvbugs 6343978). Repoint them at the venv; the pip install path did this itself.
+RUN ${ISAACLAB_PATH}/isaaclab.sh -p -c \
+      "from isaaclab.cli.commands.install import _repoint_prebundle_packages; _repoint_prebundle_packages()"
+
+# uv venv/uv sync above needed Kit's interpreter as the venv base; from here on ``uv pip``
+# should target the venv, including the interactive ``pip`` alias below.
+ENV UV_PYTHON=${VENV_PATH_ARG}/bin/python
 
 # aliasing isaaclab.sh and python for convenience
 RUN echo "export ISAACLAB_PATH=${ISAACLAB_PATH}" >> ${DOCKER_USER_HOME}/.bashrc && \
     echo "alias isaaclab=${ISAACLAB_PATH}/isaaclab.sh" >> ${DOCKER_USER_HOME}/.bashrc && \
-    echo "alias python=${ISAACLAB_PATH}/_isaac_sim/python.sh" >> ${DOCKER_USER_HOME}/.bashrc && \
-    echo "alias python3=${ISAACLAB_PATH}/_isaac_sim/python.sh" >> ${DOCKER_USER_HOME}/.bashrc && \
-    echo "alias pip='${ISAACLAB_PATH}/_isaac_sim/python.sh -m pip'" >> ${DOCKER_USER_HOME}/.bashrc && \
-    echo "alias pip3='${ISAACLAB_PATH}/_isaac_sim/python.sh -m pip'" >> ${DOCKER_USER_HOME}/.bashrc && \
-    echo "alias tensorboard='${ISAACLAB_PATH}/_isaac_sim/python.sh ${ISAACLAB_PATH}/_isaac_sim/tensorboard'" >> ${DOCKER_USER_HOME}/.bashrc && \
+    echo "alias python='${ISAACLAB_PATH}/isaaclab.sh -p'" >> ${DOCKER_USER_HOME}/.bashrc && \
+    echo "alias python3='${ISAACLAB_PATH}/isaaclab.sh -p'" >> ${DOCKER_USER_HOME}/.bashrc && \
+    echo "alias pip='uv pip'" >> ${DOCKER_USER_HOME}/.bashrc && \
+    echo "alias pip3='uv pip'" >> ${DOCKER_USER_HOME}/.bashrc && \
+    echo "alias tensorboard='${VIRTUAL_ENV}/bin/tensorboard'" >> ${DOCKER_USER_HOME}/.bashrc && \
     echo "export TZ=$(date +%Z)" >> ${DOCKER_USER_HOME}/.bashrc && \
     echo "shopt -s histappend" >> ${DOCKER_USER_HOME}/.bashrc && \
     echo "PROMPT_COMMAND='history -a'" >> ${DOCKER_USER_HOME}/.bashrc
 
-# Create the non-root runtime user after root-only image setup is complete.
-# The uid/gid 1000 match GitHub runner bind mounts used by Docker tests.
-# --non-unique is required because some base image revisions already carry
-# another user or group at uid/gid 1000.
-RUN groupadd --non-unique --gid 1000 isaaclab \
- && useradd --non-unique --uid 1000 --gid 1000 -M -l -s /bin/bash -d ${DOCKER_USER_HOME} isaaclab
-
 # The Isaac Sim image sets HUB__ARGS__DETECT_ONLY=true, which forbids OmniHub from starting.
 # omni.client still asks it to launch, so every Kit startup retries ~39 times before giving
 # up. Letting OmniHub start also needs its cache at /var/cache/hub, owned by the isaac-sim
 # user (uid 1234) upstream, to be writable by the uid 1000 runtime user.
 ENV HUB__ARGS__DETECT_ONLY=false
 
+# CI installs optional extras into the venv at test time (e.g. ``pytetwild`` for the
+# tetrahedralization feature) and a volume-mounted run executes as the runner's uid rather
+# than the image's, so the paths pip writes must be writable by a uid the image cannot know.
 RUN chown -R isaaclab:isaaclab \
         ${ISAACLAB_PATH} \
         ${DOCKER_USER_HOME} \