Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@

#### Contribution

- We currently do not acccept any contributions to this repository.
- We currently do not accept any contributions to this repository.
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ Ensure your system is set up with the following before building Isaac Sim:

> **(Linux) Ubuntu 24.04**
> Ubuntu 24.04 is not fully supported at this time. Building with Ubuntu 24.04 requires GCC/G++ 11 to be installed, GCC/G++ 12+ is not supported.
> Alternatively, use the containerized build which includes GCC 11:
> ```bash
> ./tools/docker/prep_docker_build.sh --docker-build
> ```

- **GPU**: For additional information on GPU features and requirements, see [NVIDIA GPU Requirements](https://docs.omniverse.nvidia.com/dev-guide/latest/common/technical-requirements.html)

Expand Down Expand Up @@ -167,6 +171,21 @@ isaac-sim.bat

> NOTE: If this is your first time building Isaac Sim, you will be prompted to accept the Omniverse Licensing Terms.

### Docker Deployment (Linux)

Build and run Isaac Sim in a Docker container:

```bash
# Build (one-time)
./tools/docker/prep_docker_build.sh --docker-build
./tools/docker/build_docker.sh

# Run
./tools/docker/run_docker.sh -c "./isaac-sim.sh"
```

See [tools/docker/README.md](tools/docker/README.md) for details.



## Advanced Build Options
Expand Down
11 changes: 11 additions & 0 deletions tools/docker/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ ENV NVIDIA_VISIBLE_DEVICES=all NVIDIA_DRIVER_CAPABILITIES=all
RUN touch /etc/ld.so.nohwcap

# Install dependencies
# Note: GCC 11 is included to support containerized builds on hosts with incompatible
# compilers (e.g., Ubuntu 24.04 with GCC 13). Isaac Sim requires GCC 11 for compilation.
# This enables: ./tools/docker/prep_docker_build.sh --docker-build
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
curl \
Expand All @@ -23,6 +26,14 @@ RUN apt-get update \
ca-certificates \
libglib2.0-0 \
libnghttp2-14 \
# Build and prep tools
build-essential \
gcc-11 \
g++-11 \
python3-pip \
rsync \
&& update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 \
&& update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 100 \
&& apt-get -y autoremove \
&& apt-get clean autoclean \
&& rm -rf /var/lib/apt/lists/*
Expand Down
37 changes: 32 additions & 5 deletions tools/docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Before running these scripts, ensure you have the following installed on your ho
- **rsync** - Required for file synchronization during the preparation phase
- **python3** - Required for running the preparation scripts and installing dependencies
- **Docker** - Required for building the final image
- **NVIDIA Container Toolkit** - Required for GPU access in containers

### Installing Prerequisites

Expand All @@ -31,8 +32,8 @@ Use `prep_docker_build.sh` to prepare the Docker build context:
```

#### Options:
- `--build` - Run the full Isaac Sim build sequence before preparing Docker files:
- Executes `build.sh -r`
- `--build` - Run the full Isaac Sim build sequence before preparing Docker files (requires GCC 11)
- `--docker-build` - Build Isaac Sim inside a container (no host dependencies except Docker). **Recommended for Ubuntu 24.04+** which ships with GCC 13.
- `--x86_64` - Build x86_64 container (default)
- `--aarch64` - Build aarch64 container
- `--skip-dedupe` - Skip the file deduplication process (faster but larger image)
Expand Down Expand Up @@ -63,7 +64,13 @@ Use `build_docker.sh` to build the actual Docker image:

## Example Usage

### Basic build:
### Containerized build (Ubuntu 24.04+ or no native dependencies):
```bash
./tools/docker/prep_docker_build.sh --docker-build
./tools/docker/build_docker.sh
```

### Native build (requires GCC 11):
```bash
# Prepare build environment (includes full build)
./tools/docker/prep_docker_build.sh --build
Expand All @@ -90,17 +97,37 @@ Use `build_docker.sh` to build the actual Docker image:
./tools/docker/build_docker.sh
```

## Running Isaac Sim

Use `run_docker.sh` to run the built image. Reference: [NVIDIA Container Docs](https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_container.html)

```bash
./tools/docker/run_docker.sh -c "./isaac-sim.sh" # GUI
./tools/docker/run_docker.sh -c "./runheadless.sh -v" # Headless + livestream
./tools/docker/run_docker.sh -c "./isaac-sim.sh --help" # Help
```

**Persistent cache**: Extensions and shaders are cached in `_isaac_cache/`. First run downloads ~150 extensions (~3-5 min); subsequent runs are fast.

**Cleaning**: Remove all Docker artifacts (build context and runtime cache):
```bash
./tools/docker/clean_docker.sh
```

## Important Notes

- **Build Requirements**: The `_build/$CONTAINER_PLATFORM/release` directory must exist before running the Docker preparation. Use `--build` option if you haven't built Isaac Sim yet.
- **Build Requirements**: The `_build/$CONTAINER_PLATFORM/release` directory must exist before running the Docker preparation. Use `--build` or `--docker-build` option if you haven't built Isaac Sim yet.
- **Ubuntu 24.04+**: Use `--docker-build` which includes GCC 11. Native build requires manually installing GCC 11.
- **Deduplication**: The deduplication process can significantly reduce Docker image size by replacing duplicate files with symlinks, but it takes time. Use `--skip-dedupe` for faster rebuilds during development.
- **File Paths**: The deduplication process skips files with spaces in their paths for reliability.
- **Build Context**: The final Docker build uses `_container_temp` as the build context and `tools/docker/Dockerfile` as the Dockerfile.
- **Platform**: Add the `--aarch64` flag to build for arm64 platform. It is recommended to use this flag when on an arm64 host.

## Troubleshooting

- **Error: "_build/$CONTAINER_PLATFORM/release does not exist"**: Run the script with `--build` option to build Isaac Sim first.
- **Error: "_build/$CONTAINER_PLATFORM/release does not exist"**: Run the script with `--build` or `--docker-build` option to build Isaac Sim first.
- **rsync not found**: Install rsync using your system's package manager.
- **Python requirements installation fails**: Ensure python3 and pip are properly installed.
- **Docker build fails**: Check that Docker daemon is running and you have sufficient disk space.
- **GCC version not supported (Ubuntu 24.04+)**: Use `--docker-build` which includes GCC 11.
- **No GUI window**: Check `xhost +local:docker` ran successfully and `$DISPLAY` is set.
19 changes: 19 additions & 0 deletions tools/docker/clean_docker.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
#!/bin/bash
# Clean Docker build artifacts and runtime cache

IMAGE_TAG="isaac-sim-docker:latest"
SCRIPT_DIR=$(dirname ${BASH_SOURCE})
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The variable SCRIPT_DIR uses dirname ${BASH_SOURCE} without proper quoting. This should be "${BASH_SOURCE[0]}" with quotes and array index to handle paths with spaces correctly and to follow bash best practices.

Suggested change
SCRIPT_DIR=$(dirname ${BASH_SOURCE})
SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"

Copilot uses AI. Check for mistakes.
REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"

echo "Cleaning Docker artifacts..."

# _container_temp: build context (host ownership)
rm -rf "${REPO_ROOT}/_container_temp"

# _isaac_cache: runtime cache (uid 1234 ownership, use Docker to clean)
if [[ -d "${REPO_ROOT}/_isaac_cache" ]]; then
docker run --rm --entrypoint rm -v "${REPO_ROOT}/_isaac_cache":/cache "${IMAGE_TAG}" -rf /cache
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The cleanup script attempts to use the Docker image to change ownership before removing files, but it doesn't check if the image exists. If the image has been removed or doesn't exist, this command will fail. The script should either check for image existence first or handle the error case where the image is not available (e.g., fall back to sudo rm if needed, or skip the docker run step).

Suggested change
docker run --rm --entrypoint rm -v "${REPO_ROOT}/_isaac_cache":/cache "${IMAGE_TAG}" -rf /cache
if docker image inspect "${IMAGE_TAG}" >/dev/null 2>&1; then
docker run --rm --entrypoint rm -v "${REPO_ROOT}/_isaac_cache":/cache "${IMAGE_TAG}" -rf /cache
else
echo "Warning: Docker image '${IMAGE_TAG}' not found. Skipping Docker-based cache cleanup."
fi

Copilot uses AI. Check for mistakes.
rmdir "${REPO_ROOT}/_isaac_cache" 2>/dev/null || rm -rf "${REPO_ROOT}/_isaac_cache"
fi

echo "Done."
117 changes: 94 additions & 23 deletions tools/docker/prep_docker_build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@
# Parse command line arguments
SKIP_DEDUPE=false
RUN_BUILD=false
DOCKER_BUILD=false
CONTAINER_PLATFORM=linux-x86_64
BUILDER_IMAGE="isaac-sim-builder:latest"
PACKMAN_CACHE_DIR="$(pwd)/_packman_cache"

show_help() {
cat << EOF
Expand All @@ -13,7 +16,8 @@ Usage: $0 [OPTIONS]
Prepares Docker build by generating rsync script and copying necessary files.

OPTIONS:
--build Build Isaac Sim
--build Build Isaac Sim natively (requires GCC 11)
--docker-build Build Isaac Sim inside a container (recommended for Ubuntu 24.04+)
--x86_64 Build x86_64 container (default)
--aarch64 Build aarch64 container
--skip-dedupe Skip the deduplication process
Expand All @@ -31,10 +35,40 @@ build_function() {
return 1
fi


echo "Build sequence completed successfully!"
}

docker_build_function() {
echo "Building Isaac Sim inside container..."

# Build the builder image from the Dockerfile (has GCC 11)
if ! docker build -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/; then
echo "Error: Failed to build builder image" >&2
return 1
fi

# Create the packman cache directory
# This is mounted inside the container so symlinks created during build
# point to paths that exist on both host and container
mkdir -p "$PACKMAN_CACHE_DIR"

# Run build inside container with source mounted
# Mount packman cache to the SAME path used inside container so symlinks work on host
# Run with host user's UID/GID to ensure build artifacts have correct ownership
if ! docker run --rm --user "$(id -u):$(id -g)" --entrypoint bash \
-e TERM=xterm-256color \
-v "$(pwd):/workspace" \
-v "$PACKMAN_CACHE_DIR:$PACKMAN_CACHE_DIR" \
-e PM_PACKAGES_ROOT="$PACKMAN_CACHE_DIR" \
-w /workspace "$BUILDER_IMAGE" \
-c "touch .eula_accepted && ./build.sh -r"; then
echo "Error: Containerized build failed" >&2
return 1
fi

echo "Containerized build completed successfully!"
}

# Parse command line options
while [[ $# -gt 0 ]]; do
case $1 in
Expand All @@ -46,6 +80,10 @@ while [[ $# -gt 0 ]]; do
RUN_BUILD=true
shift
;;
--docker-build)
DOCKER_BUILD=true
shift
;;
Comment on lines +83 to +86
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The script allows both --build and --docker-build flags to be specified simultaneously. If both are provided, both build methods will execute sequentially, which is likely not the intended behavior and could be confusing. Consider adding validation to ensure these flags are mutually exclusive, or document this behavior clearly in the help message.

Copilot uses AI. Check for mistakes.
--x86_64)
CONTAINER_PLATFORM=linux-x86_64
shift
Expand Down Expand Up @@ -77,39 +115,72 @@ if [[ "$RUN_BUILD" == "true" ]]; then
fi
fi

# Run containerized build if --docker-build was specified
if [[ "$DOCKER_BUILD" == "true" ]]; then
echo ""
docker_build_function
if [[ $? -ne 0 ]]; then
echo "Containerized build failed, exiting with error code 1" >&2
exit 1
fi
fi

# Check that _build/linux-x86_64 or _build/linux-aarch64 exists
if [[ ! -d "_build/${CONTAINER_PLATFORM}/release" ]]; then
echo "Error: _build/${CONTAINER_PLATFORM}/release does not exist" >&2
echo "Please rerun the script with --build" >&2
echo "Please rerun the script with --build or --docker-build" >&2
exit 1
fi


# Goes a bit faster if you have used PM_PATH_TO_SANDBOX="_"
if ! python3 -m pip install -r tools/docker/requirements.txt; then
echo "Failed to install Python requirements" >&2
exit 1
fi


if ! python3 tools/docker/generate_rsync_script.py --platform ${CONTAINER_PLATFORM} --target isaac-sim-docker --output-folder _container_temp; then
echo "Failed to generate rsync script" >&2
exit 1
fi


./generated_rsync_package.sh

# Prep steps: generate rsync, copy files
# Use container if --docker-build was specified (no host dependencies)
# Otherwise use native Python (original behavior)
if [[ "$DOCKER_BUILD" == "true" ]]; then
PACKMAN_CACHE_DIR="$(pwd)/_packman_cache"
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The variable PACKMAN_CACHE_DIR is defined twice - once at line 10 as a global variable and again at line 140 inside the conditional block. The redefinition at line 140 is redundant since the variable is already set at the top of the script. Consider removing this duplicate assignment.

Suggested change
PACKMAN_CACHE_DIR="$(pwd)/_packman_cache"

Copilot uses AI. Check for mistakes.

if ! docker build -q -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/ >/dev/null; then
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docker build command at line 142 uses the -q (quiet) flag and redirects output to /dev/null, which will suppress error messages if the build fails. This makes debugging difficult. Consider removing the -q flag or at least not redirecting stderr, so users can see what went wrong if the build fails.

Suggested change
if ! docker build -q -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/ >/dev/null; then
if ! docker build -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/; then

Copilot uses AI. Check for mistakes.
echo "Error: Failed to build prep image" >&2
exit 1
fi

if ! docker run --rm --user "$(id -u):$(id -g)" --entrypoint bash \
-v "$(pwd):/workspace" \
-v "$PACKMAN_CACHE_DIR:$PACKMAN_CACHE_DIR" \
-e PM_PACKAGES_ROOT="$PACKMAN_CACHE_DIR" \
-w /workspace \
"$BUILDER_IMAGE" \
-c "
pip install -q --break-system-packages -r tools/docker/requirements.txt && \
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The --break-system-packages flag is used with pip install, which is generally discouraged as it can interfere with system-managed packages. Since this is running inside a container where the environment is controlled, consider using a virtual environment or user-level install (pip install --user) instead for better practice, even in containerized environments.

Suggested change
pip install -q --break-system-packages -r tools/docker/requirements.txt && \
python3 -m pip install -q --user -r tools/docker/requirements.txt && \

Copilot uses AI. Check for mistakes.
python3 tools/docker/generate_rsync_script.py --platform ${CONTAINER_PLATFORM} --target isaac-sim-docker --output-folder _container_temp && \
./generated_rsync_package.sh && \
find _container_temp -type d -empty -delete && \
cp -r tools/docker/data/* _container_temp
"; then
echo "Error: Prep failed" >&2
exit 1
fi
else
echo "Preparing Docker build context..."

if ! python3 -m pip install -r tools/docker/requirements.txt; then
echo "Failed to install Python requirements" >&2
exit 1
fi

echo "Removing empty folders"
# Remove empty folders from container temp
find _container_temp -type d -empty -delete
if ! python3 tools/docker/generate_rsync_script.py --platform ${CONTAINER_PLATFORM} --target isaac-sim-docker --output-folder _container_temp; then
echo "Failed to generate rsync script" >&2
exit 1
fi

./generated_rsync_package.sh

echo "Copying data from tools/docker/data"
echo "Removing empty folders"
find _container_temp -type d -empty -delete

cp -r tools/docker/data/* _container_temp
echo "Copying data from tools/docker/data"
cp -r tools/docker/data/* _container_temp
fi


find_chained_symlinks(){
Expand Down
19 changes: 16 additions & 3 deletions tools/docker/run_docker.sh
Original file line number Diff line number Diff line change
@@ -1,6 +1,19 @@
#!/bin/bash
PRIVACY_EMAIL="${PRIVACY_EMAIL:-user@example.com}" # Allow override via environment

IMAGE_TAG="isaac-sim-docker:latest"
PRIVACY_EMAIL="user@example.com"
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The variable PRIVACY_EMAIL is now hardcoded to "user@example.com" and the ability to override it via environment variable has been removed. This is a breaking change for users who may have been setting this environment variable to a custom value. Consider keeping the environment variable override capability using: PRIVACY_EMAIL="${PRIVACY_EMAIL:-user@example.com}"

Suggested change
PRIVACY_EMAIL="user@example.com"
PRIVACY_EMAIL="${PRIVACY_EMAIL:-user@example.com}"

Copilot uses AI. Check for mistakes.
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
CACHE_DIR="${REPO_ROOT}/_isaac_cache"

xhost +local:docker &>/dev/null || true
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The xhost +local:docker call unconditionally relaxes X11 access control for your current display, effectively allowing any local client mapped to the docker user (i.e., any rootless Docker container) to connect to and control your X session. A compromised or malicious container image could then capture keystrokes, scrape window contents, or inject input into host applications. Consider narrowing X11 permissions to only the specific user/container needed and restoring the original xhost configuration after the container exits instead of leaving this broad rule in place.

Copilot uses AI. Check for mistakes.

# Create cache directory with container user ownership (uid 1234)
mkdir -p "${CACHE_DIR}"
Copy link

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The script creates a cache directory and attempts to change its ownership using a Docker container before the image is guaranteed to exist. If the user runs this script before building the image (isaac-sim-docker:latest), the chown command will fail with "image not found". Consider checking if the image exists first, or handle the error gracefully, or document that this script should only be run after building the image.

Suggested change
mkdir -p "${CACHE_DIR}"
mkdir -p "${CACHE_DIR}"
if ! docker image inspect "${IMAGE_TAG}" > /dev/null 2>&1; then
echo "Error: Docker image '${IMAGE_TAG}' not found. Please build or pull it before running this script." >&2
exit 1
fi

Copilot uses AI. Check for mistakes.
docker run --rm --entrypoint chown -v "${CACHE_DIR}":/cache "${IMAGE_TAG}" -R 1234:1234 /cache

docker run --name isaac-sim --entrypoint bash -it --gpus all -e "ACCEPT_EULA=Y" --rm \
--network=host -e "PRIVACY_CONSENT=Y" -e "PRIVACY_USERID=${PRIVACY_EMAIL}" isaac-sim-docker:latest \
"$@"
--network=host -e "PRIVACY_CONSENT=Y" -e "PRIVACY_USERID=${PRIVACY_EMAIL}" \
-e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
-v "${CACHE_DIR}":/isaac-sim/.local/share/ov \
"${IMAGE_TAG}" "$@"
Loading