How to Enable and Use GPU/CUDA Support with LabNow AI Images for Deep Learning

Enable GPU acceleration in LabNow AI containers by installing the NVIDIA Container Toolkit on your host, then running the image with the --gpus all flag to expose CUDA devices for deep learning workloads.

LabNow AI provides pre-built Docker images that bundle PyTorch, TensorFlow, and other deep learning frameworks with NVIDIA CUDA support. According to the lab-foundation source code, these GPU-enabled images are constructed from the docker_cuda/nvidia-cuda.Dockerfile and published through automated CI workflows. This guide walks you through configuring your host system and running containers with full GPU access for accelerated model training and inference.

Prerequisites and Architecture

Before running GPU-enabled containers, your host system must provide the underlying hardware and runtime support.

Host NVIDIA Driver Requirements

The host machine must have a compatible NVIDIA driver installed that supplies the GPU kernel modules. This is a prerequisite before any container can access the GPU. Verify your driver installation with:

nvidia-smi

This command should display your GPU model, driver version, and CUDA version.

NVIDIA Container Toolkit

The NVIDIA Container Toolkit (nvidia-ctk) bridges the host driver to Docker, enabling the --gpus flag functionality. LabNow provides an offline installation procedure in [docker_cuda/README.md](https://github.com/labnow-ai/lab-foundation/blob/main/docker_cuda/README.md) for air-gapped environments. This method extracts Debian packages and configures Docker to use the nvidia runtime as the default.

Image Layer Architecture

The GPU images follow a layered architecture:

• Base CUDA layer: docker_cuda/nvidia-cuda.Dockerfile extends the official NVIDIA CUDA images and sets ENV NVIDIA_DISABLE_REQUIRE=1 to disable strict CUDA version checking, allowing flexible framework versions. It also installs monitoring utilities like nvtop.
• Core stack: Images inherit from docker_core and docker_atom to add Python, R, Julia, and curated AI libraries.
• CI/CD: The [.github/workflows/build-docker-gpu.yml](https://github.com/labnow-ai/lab-foundation/blob/main/.github/workflows/build-docker-gpu.yml) workflow automates building and pushing GPU-enabled tags to container registries.

Installing the NVIDIA Container Toolkit

For systems with internet access, install the toolkit using the official NVIDIA repositories. For offline or air-gapped machines, follow the manual extraction steps documented in [docker_cuda/README.md](https://github.com/labnow-ai/lab-foundation/blob/main/docker_cuda/README.md).

After installation, restart the Docker daemon to register the NVIDIA runtime:

sudo systemctl restart docker

Verify the runtime is configured:

docker info | grep nvidia

Running LabNow AI Images with GPU Support

Once the host is configured, you can run GPU-accelerated containers using standard Docker commands with GPU device requests.

Pulling GPU-Enabled Images

LabNow publishes GPU-specific tags (e.g., labnow/nvidia-cuda or framework-specific variants like labnow/pytorch-cuda). Pull the base CUDA image:

docker pull labnow/nvidia-cuda:latest

Basic Docker Run with GPU Access

Expose all GPUs to the container using the --gpus all flag:

docker run --gpus all -it --rm labnow/nvidia-cuda bash

Inside the container, verify CUDA accessibility:

nvcc --version
nvidia-smi

These commands confirm the CUDA compiler and driver libraries are properly mounted from the host.

Docker Compose Configuration

For multi-service applications, specify GPU reservations in your docker-compose.yml:

version: "3.9"
services:
  trainer:
    image: labnow/pytorch-cuda:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    volumes:
      - ./project:/workspace
    working_dir: /workspace
    command: python train.py

Deploy with:

docker-compose up

Verifying CUDA and GPU Access

After starting a container, verify that deep learning frameworks can detect the GPU hardware.

System-Level Verification

Check CUDA compiler availability and GPU status:

docker run --gpus all labnow/nvidia-cuda nvcc --version
docker run --gpus all labnow/nvidia-cuda nvidia-smi

Python Framework Validation

Test PyTorch GPU access:

docker run --gpus all -v $(pwd):/workspace labnow/pytorch-cuda python -c "
import torch
print('CUDA available:', torch.cuda.is_available())
print('GPU count:', torch.cuda.device_count())
print('Device name:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'None')
x = torch.randn(1000, 1000, device='cuda')
y = torch.randn(1000, 1000, device='cuda')
print('Tensor operation result:', (x @ y).mean().item())
"

Test TensorFlow GPU access:

docker run --gpus all labnow/tensorflow-cuda python -c "
import tensorflow as tf
print('GPUs:', tf.config.list_physical_devices('GPU'))
"

Key Source Files

Understanding the source configuration helps customize GPU environments:

• docker_cuda/nvidia-cuda.Dockerfile — Defines the CUDA base image, sets NVIDIA_DISABLE_REQUIRE=1, and installs utilities like nvtop.
• [docker_cuda/README.md](https://github.com/labnow-ai/lab-foundation/blob/main/docker_cuda/README.md) — Documents offline installation of the NVIDIA Container Toolkit for air-gapped deployments.
• [.github/workflows/build-docker-gpu.yml](https://github.com/labnow-ai/lab-foundation/blob/main/.github/workflows/build-docker-gpu.yml) — GitHub Actions workflow that builds and publishes GPU-enabled images to Docker Hub and Quay.io.

Summary

• LabNow AI images provide pre-configured CUDA environments for deep learning without manual toolkit installation inside containers.
• Host prerequisites require the NVIDIA driver and NVIDIA Container Toolkit installed before running GPU containers.
• GPU exposure uses the --gpus all flag in docker run or the deploy.resources.reservations.devices configuration in Docker Compose.
• Verification relies on nvidia-smi, nvcc, and framework-specific checks like torch.cuda.is_available().
• Source configuration is managed in docker_cuda/nvidia-cuda.Dockerfile with automated builds via [.github/workflows/build-docker-gpu.yml](https://github.com/labnow-ai/lab-foundation/blob/main/.github/workflows/build-docker-gpu.yml).

Frequently Asked Questions

How do I verify that my host GPU is properly configured for Docker?

Run nvidia-smi on the host to confirm the driver is loaded. Then execute docker run --gpus all labnow/nvidia-cuda nvidia-smi to verify the GPU is accessible inside a container. If both commands display GPU information, your host is properly configured.

What is the purpose of the NVIDIA_DISABLE_REQUIRE environment variable in the Dockerfile?

As implemented in docker_cuda/nvidia-cuda.Dockerfile, setting ENV NVIDIA_DISABLE_REQUIRE=1 disables the strict CUDA version compatibility check performed by the NVIDIA runtime. This allows containers to run with varying CUDA toolkit versions and prevents initialization errors when mixing driver and toolkit versions.

Can I restrict GPU access to specific devices rather than using all GPUs?

Yes. Instead of --gpus all, specify device indices: --gpus "device=0,2" exposes only the first and third GPUs. In Docker Compose, change count: all to count: 1 or use specific device IDs under the devices list to limit GPU visibility for resource management.

Do I need to install CUDA inside the container when using LabNow AI images?

No. The LabNow AI images come with the CUDA toolkit, cuDNN, and framework binaries pre-installed according to the docker_cuda/nvidia-cuda.Dockerfile build process. You only need the NVIDIA driver and Container Toolkit on the host; the container receives the CUDA libraries and runtime through the image layers and mounted driver files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}