Run ROCm Docker containers

Run ROCm Docker containers#

2026-06-02

4 min read time

Applies to Linux

Docker is a popular way to run ROCm workloads in a consistent, reproducible environment. There are two ways to expose AMD GPUs to Docker containers:

Prerequisites#

Regardless of which approach you use, the following are required on the host system:

With the AMD Container Runtime Toolkit#

The AMD Container Runtime Toolkit provides two mechanisms for GPU injection: CDI (recommended) and the amd-container-runtime. Both require installing the toolkit first.

  1. Install the toolkit by following the Quick Start Guide (AMD Container Runtime Toolkit docs).

  2. See Running Workloads (AMD Container Runtime Toolkit docs) to get started running containerized ROCm applications on AMD GPUs.

Without the AMD Container Toolkit#

If you prefer not to install the AMD Container Toolkit, or you’re using older versions of Docker Engine, you can pass GPU device nodes directly to the container using Docker’s --device flag. This approach requires no additional software beyond Docker.

docker run -it --rm \
    --device /dev/kfd \
    --device /dev/dri \
    --security-opt seccomp=unconfined \
    <image>

The purpose of each option:

  • --device /dev/kfd

    The main compute interface, shared by all GPUs.

  • --device /dev/dri

    Contains the Direct Rendering Interface (DRI) device nodes for each GPU. Passing the whole directory grants access to all GPUs. To restrict access to specific GPUs, see Restricting GPU access.

  • --security-opt seccomp=unconfined (optional)

    Enables memory mapping. Recommended for HPC workloads that use numactl for GPU/CPU affinity mappings. See Optional security options (Docker docs).

Restricting GPU access#

Tip

AMD Container Runtime Toolkit simplifies GPU selection, removing the need to manually map the render nodes. This is recommended if your use case needs fine-grained GPU selection. See Running Workloads (AMD Container Toolkit Runtime docs) for more information.

By default, --device /dev/dri grants access to all GPUs on the system. To limit a container to specific GPUs, pass their individual render nodes instead.

List available render nodes on the host:

ls /dev/dri/render*

GPU render nodes are typically named renderD128, renderD129, and so on. Pass them individually alongside /dev/kfd:

docker run --device /dev/kfd \
    --device /dev/dri/renderD128 \
    --device /dev/dri/renderD129 \
    <image>

Note

When GPUs are partitioned (for example, an Instinct MI300X or MI350X in DPX, QPX, or CPX mode), each partition appears as a separate render node. In CPX mode, renderD128 through renderD136 are partitions of the first physical GPU, and renderD137 is the second GPU. Account for this when selecting render nodes. See GPU partitioning for details.

Docker Compose#

Docker Compose can simplify complex Docker invocations. See Docker Compose usage for AMD Container Toolkit configuration examples.

For manual Docker device passthrough, use the devices key in your Compose file:

services:
  myapp:
    image: <image>
    devices:
      - /dev/kfd
      - /dev/dri

Verifying GPU access#

Inside any container with ROCm installed, rocminfo and amd-smi list enumerate only the GPUs passed into that container. On the host, they enumerate all ROCm-capable GPUs.

rocminfo and amd-smi are provided by the ROCm software stack. Run either tool to confirm the expected GPUs are visible.

Docker images#

The ROCm Docker repository hosts Dockerfiles for building ROCm-capable containers. Pre-built images are available on Docker Hub:

  • rocm/rocm-terminal — minimal image with prerequisites to build HIP applications, without any libraries.

  • ROCm dev images — a variety of OS and ROCm version combinations, suitable as a base for building applications.

AMD also provides pre-built images for AI and HPC applications through Infinity Hub, including suggested parameters for benchmarking.

Contents