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

> Enable GPU CUDA support in LabNow AI images for deep learning. Install NVIDIA Container Toolkit and use the --gpus all flag for accelerated workloads. Boost your AI development now.

- Repository: [LabNow.ai/lab-foundation](https://github.com/labnow-ai/lab-foundation)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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](https://github.com/labnow-ai/lab-foundation) source code, these GPU-enabled images are constructed from the [`docker_cuda/nvidia-cuda.Dockerfile`](https://github.com/labnow-ai/lab-foundation/blob/main/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:

```bash
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)](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`](https://github.com/labnow-ai/lab-foundation/blob/main/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)](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)](https://github.com/labnow-ai/lab-foundation/blob/main/docker_cuda/README.md).

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

```bash
sudo systemctl restart docker

```

Verify the runtime is configured:

```bash
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:

```bash
docker pull labnow/nvidia-cuda:latest

```

### Basic Docker Run with GPU Access

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

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

```

Inside the container, verify CUDA accessibility:

```bash
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`](https://github.com/labnow-ai/lab-foundation/blob/main/docker-compose.yml):

```yaml
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/labnow-ai/lab-foundation/blob/main/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)](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)](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`](https://github.com/labnow-ai/lab-foundation/blob/main/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)](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`](https://github.com/labnow-ai/lab-foundation/blob/main/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`](https://github.com/labnow-ai/lab-foundation/blob/main/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.