> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/Isaac-GR00T/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker deployment

> Deploy GR00T in a containerized environment with CUDA support and pre-installed dependencies

Run GR00T in a Docker container with all dependencies pre-configured, including CUDA support, PyTorch, PyTorch3D, and the complete GR00T codebase.

## Prerequisites

<Steps>
  ### Install Docker

  Install Docker version 20.10 or later:

  ```bash theme={null}
  curl -fsSL https://get.docker.com -o get-docker.sh
  sudo sh get-docker.sh
  ```

  ### Post-installation setup

  Configure Docker to run without sudo:

  ```bash theme={null}
  sudo usermod -aG docker $USER
  newgrp docker
  ```

  Verify installation:

  ```bash theme={null}
  docker run hello-world
  ```

  ### Install NVIDIA Container Toolkit

  Install the NVIDIA Container Toolkit for GPU access:

  ```bash theme={null}
  distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
  curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
  curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

  sudo apt-get update
  sudo apt-get install -y nvidia-container-toolkit
  sudo systemctl restart docker
  ```

  Test GPU access:

  ```bash theme={null}
  docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
  ```
</Steps>

## Building the image

The Docker image is based on NVIDIA's PyTorch container (`nvcr.io/nvidia/pytorch:25.04-py3`) and includes all GR00T dependencies.

### Build command

From the project root:

```bash theme={null}
cd docker
bash build.sh
```

<Note>
  Make sure you are using a bash environment. The build process will take several minutes and requires several GB of disk space.
</Note>

### Build output

The build creates an image named `gr00t-dev` with:

* NVIDIA PyTorch 25.04 base
* CUDA 12.x support
* Python 3.10
* PyTorch3D
* All dependencies from `pyproject.toml`
* GR00T codebase at `/workspace/gr00t/`

### Rebuild with no cache

Force a clean rebuild:

```bash theme={null}
bash build.sh --no-cache
```

## Running the container

### Interactive shell (baked code)

Run with the code baked into the image:

```bash theme={null}
docker run -it --rm --gpus all gr00t-dev /bin/bash
```

This starts an interactive shell in `/workspace/gr00t/` with all dependencies ready.

### Development mode (mounted code)

Mount your local codebase for live editing:

```bash theme={null}
cd docker  # Must run from docker/ directory
docker run -it --rm --gpus all \
    -v $(pwd)/..:/workspace/gr00t \
    gr00t-dev /bin/bash
```

<Note>
  Changes to your local GR00T code will be immediately reflected inside the container. This is ideal for development and debugging.
</Note>

### Custom working directory

Start in a specific directory:

```bash theme={null}
docker run -it --rm --gpus all \
    -w /workspace/gr00t/examples/LIBERO \
    gr00t-dev /bin/bash
```

## Running inference in Docker

### Start policy server

Run the GR00T server inside the container:

```bash theme={null}
docker run -it --rm --gpus all \
    -p 5555:5555 \
    gr00t-dev /bin/bash -c "
    uv run python gr00t/eval/run_gr00t_server.py \
        --embodiment-tag GR1 \
        --model-path nvidia/GR00T-N1.6-3B \
        --host 0.0.0.0 \
        --port 5555
    "
```

The `-p 5555:5555` flag exposes the server port to the host machine.

### Run inference script

Execute standalone inference:

```bash theme={null}
docker run -it --rm --gpus all \
    -v /path/to/data:/data \
    gr00t-dev /bin/bash -c "
    uv run python scripts/deployment/standalone_inference_script.py \
        --model-path nvidia/GR00T-N1.6-3B \
        --dataset-path /data/gr1.PickNPlace \
        --embodiment-tag GR1 \
        --inference-mode pytorch
    "
```

### Mount datasets

Mount external data directories:

```bash theme={null}
docker run -it --rm --gpus all \
    -v /path/to/datasets:/workspace/datasets \
    -v /path/to/checkpoints:/workspace/checkpoints \
    gr00t-dev /bin/bash
```

## Training in Docker

### Mount output directory

```bash theme={null}
docker run -it --rm --gpus all \
    -v /path/to/datasets:/workspace/datasets \
    -v /path/to/outputs:/workspace/outputs \
    gr00t-dev /bin/bash -c "
    CUDA_VISIBLE_DEVICES=0 uv run python gr00t/experiment/launch_finetune.py \
        --base-model-path nvidia/GR00T-N1.6-3B \
        --dataset-path /workspace/datasets/my_dataset \
        --embodiment-tag GR1 \
        --output-dir /workspace/outputs/run_1 \
        --max-steps 2000
    "
```

### Multi-GPU training

Specify GPU devices:

```bash theme={null}
docker run -it --rm --gpus '"device=0,1"' \
    gr00t-dev /bin/bash -c "
    export NUM_GPUS=2
    CUDA_VISIBLE_DEVICES=0,1 uv run python gr00t/experiment/launch_finetune.py \
        --num-gpus 2 \
        --base-model-path nvidia/GR00T-N1.6-3B \
        --dataset-path /workspace/datasets/my_dataset
    "
```

## Docker Compose

Create `docker-compose.yml` for easier container management:

```yaml theme={null}
version: '3.8'

services:
  gr00t-server:
    image: gr00t-dev
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    ports:
      - "5555:5555"
    volumes:
      - ./datasets:/workspace/datasets
      - ./checkpoints:/workspace/checkpoints
    command: >
      uv run python gr00t/eval/run_gr00t_server.py
        --embodiment-tag GR1
        --model-path /workspace/checkpoints/gr00t-n1.6-3b
        --host 0.0.0.0
        --port 5555
```

Launch with:

```bash theme={null}
docker-compose up
```

## Advanced usage

### Persistent container

Keep a container running in the background:

```bash theme={null}
docker run -d --name gr00t-dev --gpus all \
    -v $(pwd)/..:/workspace/gr00t \
    gr00t-dev tail -f /dev/null
```

Execute commands in the running container:

```bash theme={null}
docker exec -it gr00t-dev bash
docker exec gr00t-dev uv run python gr00t/eval/run_gr00t_server.py --embodiment-tag GR1
```

Stop and remove:

```bash theme={null}
docker stop gr00t-dev
docker rm gr00t-dev
```

### Environment variables

Pass environment variables:

```bash theme={null}
docker run -it --rm --gpus all \
    -e WANDB_API_KEY=your_key \
    -e CUDA_VISIBLE_DEVICES=0 \
    gr00t-dev /bin/bash
```

### Network configuration

Use host networking for minimal latency:

```bash theme={null}
docker run -it --rm --gpus all \
    --network host \
    gr00t-dev /bin/bash
```

<Warning>
  Host networking removes network isolation. Only use on trusted networks.
</Warning>

## Troubleshooting

### GPU not detected

Verify NVIDIA Container Toolkit:

```bash theme={null}
nvidia-container-toolkit --version
```

Restart Docker daemon:

```bash theme={null}
sudo systemctl restart docker
```

Test GPU access:

```bash theme={null}
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi
```

If `nvidia-smi` fails inside the container, check:

1. NVIDIA drivers on host:
   ```bash theme={null}
   nvidia-smi  # Run on host
   ```

2. Docker daemon configuration:

   ```bash theme={null}
   cat /etc/docker/daemon.json
   ```

   Should include:

   ```json theme={null}
   {
     "runtimes": {
       "nvidia": {
         "path": "nvidia-container-runtime",
         "runtimeArgs": []
       }
     }
   }
   ```

### Permission errors

Add user to docker group:

```bash theme={null}
sudo usermod -aG docker $USER
newgrp docker
```

Or run with sudo:

```bash theme={null}
sudo docker run -it --rm --gpus all gr00t-dev /bin/bash
```

### Build failures

Check disk space:

```bash theme={null}
df -h
```

Clean Docker cache:

```bash theme={null}
docker system prune -a
```

Rebuild without cache:

```bash theme={null}
cd docker
sudo bash build.sh --no-cache
```

### Out of memory during build

Increase Docker memory limit in Docker Desktop settings or in `/etc/docker/daemon.json`:

```json theme={null}
{
  "default-runtime": "nvidia",
  "memory": "16g",
  "cpus": "8"
}
```

Restart Docker:

```bash theme={null}
sudo systemctl restart docker
```

### Container exits immediately

Check logs:

```bash theme={null}
docker logs <container_id>
```

Run with verbose output:

```bash theme={null}
docker run -it --rm --gpus all gr00t-dev /bin/bash -x
```

## Best practices

### Use .dockerignore

Create `.dockerignore` to exclude unnecessary files:

```
__pycache__/
*.pyc
.git/
.venv/
outputs/
checkpoints/
```

### Tag images by version

```bash theme={null}
docker build -t gr00t-dev:v1.6 .
docker build -t gr00t-dev:latest .
```

### Resource limits

Limit container resources:

```bash theme={null}
docker run -it --rm --gpus all \
    --memory="32g" \
    --cpus="8" \
    gr00t-dev /bin/bash
```

### Clean up unused images

Remove old images:

```bash theme={null}
docker image prune -a
```

## Deployment scenarios

### Cloud deployment (AWS, GCP, Azure)

Push image to container registry:

```bash theme={null}
# Tag for registry
docker tag gr00t-dev:latest your-registry.com/gr00t-dev:latest

# Push
docker push your-registry.com/gr00t-dev:latest
```

Run on cloud GPU instance:

```bash theme={null}
docker pull your-registry.com/gr00t-dev:latest
docker run -it --rm --gpus all \
    -p 5555:5555 \
    your-registry.com/gr00t-dev:latest
```

### Kubernetes deployment

Create deployment manifest:

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gr00t-server
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: gr00t
        image: your-registry.com/gr00t-dev:latest
        resources:
          limits:
            nvidia.com/gpu: 1
        ports:
        - containerPort: 5555
```

### CI/CD integration

Use in automated testing:

```bash theme={null}
# In CI pipeline
docker build -t gr00t-dev:ci .
docker run --rm --gpus all gr00t-dev:ci \
    uv run pytest tests/
```