Docker Images

CV-CUDA provides pre-built Docker images for development and building redistributable packages. All images support both x86_64 (AMD64) and aarch64 (ARM64) architectures through multi-architecture manifests.

Overview

Two main categories of images:

  1. Builder Images - Manylinux 2_28 based for creating redistributable packages (wheels, debs, tarballs)

  2. Development Images - Ubuntu-based with complete development and testing environments

Docker automatically selects the appropriate architecture when pulling images.

Builder Images

Manylinux-based images with CUDA toolkit for building CV-CUDA packages compatible with a wide range of Linux distributions.

Builder Image Variants

Image Name

GCC Version

CUDA Version

Purpose

builder_cu12.5.0_gcc10

10

12.5.0

CUDA 12.5 builds (multi-arch)

builder_cu12.9.0_gcc10

10

12.9.0

CUDA 12.9 builds (multi-arch)

builder_cu13.0.1_gcc10

10

13.0.1

CUDA 13.0 builds (multi-arch)

Build Dependencies Hierarchy:

┌─────────────────┐    ┌─────────────────┐
│   ManyLinux     │    │   Ubuntu 22.04  │
└─────────┬───────┘    └─────────┬───────┘
          │                      │
          │ + GCC                │ + CUDA Toolkit
          │                      │
          ▼                      ▼
┌─────────────────┐    ┌─────────────────┐
│ GCC Base Images │    │ CUDA Base Images│
└─────────┬───────┘    └─────────┬───────┘
          │                      │
          │ BASE                 │ COPY CUDA
          └──────────┬───────────┘
                     │
                     │ Combine
                     ▼
           ┌─────────────────┐
           │ Builder Images  │
           └─────────────────┘

Builder Image Features:

  • CMake 3.24.3

  • Python 3.9-3.14 from ManyLinux

  • Documentation tools (Sphinx 7.4.7/8.1.3, sphinx_rtd_theme, breathe)

  • Development tools (patchelf 0.17.2, setuptools, wheel, clang 14.0)

  • Full CUDA toolkit

  • git-lfs for large files

Development Images

Full Ubuntu-based environments with multiple Python versions, NumPy, and PyTorch for development and testing.

Base: NVIDIA CUDA images (nvidia/cuda:${CUDA_VER}-devel-ubuntu${UB_VER})

Key Features:

  • Multiple GCC versions (10, 11, 12, 13, 14 on Ubuntu 24.04)

  • Multiple Clang versions (11 on Ubuntu 22.04, 14 on all)

  • CMake 3.24.3, ninja-build, ccache

  • Testing frameworks (Google Test/Mock, pytest)

  • ML frameworks (PyTorch, NumPy with version-specific wheels)

  • Documentation tools (Doxygen, Sphinx)

  • Development tools (git, git-lfs, pre-commit, shellcheck)

Python Requirements Files

CV-CUDA uses multiple requirements files for different purposes:

Requirements Files

File

Purpose

requirements.sys_python.txt

System Python only: documentation (Sphinx, Breathe), wheel building (setuptools, wheel, build, patchelf, auditwheel), linting (flake8)

requirements.no_torch_no_numpy.txt

All Python versions: testing tools (pytest, typing-extensions) - excludes PyTorch and NumPy

requirements.numpy1.txt

NumPy 1.x for Python 3.9-3.12 (1.26.4). Not compatible with Python 3.13+

requirements.numpy2.txt

NumPy 2.x with version constraints: 2.0.2 (Python 3.9), 2.2.6 (Python 3.10-3.13), 2.3.3 (Python 3.14)

PyTorch is installed separately per Python version in the Dockerfiles (not via requirements files).

Building the Images

Use the build_dockers.sh script in the docker/ directory.

Usage:

# Build locally for native architecture only (default)
./build_dockers.sh

# Explicitly force local build mode
./build_dockers.sh "" local

# Build and push multi-arch images to registry
./build_dockers.sh $REGISTRY_PREFIX multiarch

Modes:

  • local: Build for native architecture only, load into local Docker (default when no registry)

  • multiarch: Build for both x86_64 and aarch64, push to registry (requires registry)

Using the Images

Running a development image, mounting source code for development:

docker run -it --gpus all \
  -v /path/to/cvcuda:/workspace \
  devel_u22.04_cu12.5.0_num1_torch2.8.0:v2

Using a builder image for creating manylinux-compatible wheels:

docker run -it --gpus all \
  -v /path/to/cvcuda:/workspace \
  builder_cu12.5.0_gcc10:v1

Maintenance

Updating Image Versions

  1. Increment VERSION variable in build_dockers.sh

  2. Run build script to create new image versions

Adding New CUDA Versions

  1. Create new Dockerfile.cuda{version}.deps with architecture detection - Use dpkg --print-architecture to detect amd64 vs arm64 - Download appropriate CUDA installer (linux.run for x86_64, linux_sbsa.run for aarch64)

  2. Add corresponding sections in build_dockers.sh

  3. Update development image variants

Adding New Python Versions

  • Builder images: Python versions come from base ManyLinux

  • Development images: Update build arguments in build_dockers.sh:

    --build-arg "PYTHON_VERSIONS=3.9 3.10 3.11 3.12 3.13 3.14"

Troubleshooting

Build Failures

  • Verify Docker buildx is installed

  • Ensure sufficient disk space for multi-stage builds

  • Check network connectivity for downloading CUDA installers

Cache Issues

  • Clear build cache: docker system prune

  • Remove and recreate buildx builder:

    docker buildx rm cvcuda_multiarch_builder

Registry Authentication

  • Authenticate before using REGISTRY_PREFIX

  • Use docker login for private registries

See Also