CUDA and the driver
CUDA is NVIDIA's toolkit for programs that run on a GPU. Hangar runs one NVIDIA driver branch on every GPU instance, and your image contains the CUDA version that the image was built for. The host supplies only the driver.
The driver
- Branch: 615.71, with the open kernel modules. This is the newest branch in NVIDIA's Amazon Linux 2023 repository on 27 October 2026. On that date the repository held no R580 long-term build. Hangar moves the image to a long-term branch when NVIDIA publishes one there.
- Version: each image release names its exact driver, 615.71.10 at the first release. The changelog lists the driver of every release. The release manifest digest on each job certificate fixes the driver.
- On the host: the driver, NVIDIA's data centre GPU manager and the container toolkit. The host has no CUDA toolkit.
The CUDA versions a job can use
| The image is built for | How it runs |
|---|---|
| CUDA 11.8 to 13.0 | Directly on the 615.71 driver [verify the newest direct CUDA version at the first session] |
| CUDA 13.1 to 13.4 | Through NVIDIA's forward compatibility libraries, which NVIDIA's CUDA base images contain [verify] |
These frameworks work in this range, as their releases state: PyTorch 2.14 (CUDA 12.6, 13.0 and 13.2 builds), vLLM 0.31.0 (CUDA 13.0), JAX with jax[cuda13], TensorRT-LLM 1.2 (CUDA 13.1) and NVIDIA NGC 26.08 containers (CUDA 13.4.1).
The L4 image
The instant GPUs (the L4 and the fractional L4) boot a separate image. Hangar builds that image from the same description, with its g6 profile. The L4 image has the same driver branch at the same version as the H100 image of the same release. The range above therefore applies to the L4 unchanged: CUDA 11.8 to 13.0 directly, and 13.1 to 13.4 through forward compatibility [verify on the fractional L4 at its first session].
- The L4 has compute capability 8.9. An image runs on the L4 when the image contains code built for
sm_89, or PTX that the driver compiles at start. - A job on the fractional L4 has 3 GB of GPU memory, and a job on the L4 has 24 GB.
How the GPU reaches the container
At container start, the Container Device Interface (CDI) gives the job its GPUs and the driver's user-space libraries from the measured image. The image supplies everything else.
The preflight
The preflight is the check that Hangar runs on every image before a job. Hangar checks each image when you push or register the image, and again when Hangar stages the image. Hangar accepts a job only for an image that passed.
The check reads the CUDA version that the image declares. The image declares the version in its CUDA_VERSION environment variable or in NVIDIA's com.nvidia.cuda.version label. The job starts only when that version is in the range above. An image that declares no version runs on the driver directly. An example is an image whose framework bundles its own CUDA runtime.
When the version is outside the range, the job does not start and Hangar shows one sentence, for example:
"This image needs CUDA 14.0, and Hangar's driver carries CUDA 11.8 to 13.4. Rebuild the image on a CUDA 13.4 or earlier base."
The same check confirms these things:
- The image is a container image: its manifest, config and layer media types are OCI or Docker image types.
- The image is built for
linux/amd64. - The image has an entrypoint or a command.
- The image fits the slot's image allowance of 200 GB compressed.
An image built for linux/arm64 is checked for the CPU pool instead, with that pool's allowance of 8 GiB and no CUDA rule. Hangar refuses a GPU job of such an image when you submit the job.
Hangar checks a multi-platform image once for each platform that a Hangar pool runs. Hangar checks the linux/amd64 image with the GPU rules, and the linux/arm64 image with the CPU pool's rules. A GPU job needs the linux/amd64 result to be passed.
GET /v1/images shows each image's result. preflight is the result for the image that a GPU job takes: the linux/amd64 image, else the linux/arm64 image. A passed image shows its platform, CUDA version and entrypoint in preflight_detail. A failed image shows the reason and the next step in preflight_error. preflight_detail.platforms contains the result for each platform that the image has, keyed linux/amd64 and linux/arm64, in the same shape. The result belongs to the digest, so a tag takes the result of the digest that the tag names.