Ultralytics YOLO - Python 3.13 with Docker & UV

A minimal, production-ready Docker setup for Ultralytics YOLO with Python 3.13, NVIDIA GPU support, and UV package manager.

Features

• Python 3.13: Latest Python version
• Ultralytics: State-of-the-art YOLO models for object detection
• NVIDIA GPU Support: CUDA 12.6 runtime for GPU acceleration
• UV Package Manager: Fast, modern Python package manager
• Multi-stage Build: Optimized for minimal image size
• Security: Non-root user execution

Project Structure

.
├── Dockerfile          # Multi-stage Docker build with NVIDIA support
├── pyproject.toml      # Project dependencies managed by UV
├── main.py             # Example application
├── .dockerignore       # Docker build optimization
└── README.md           # This file

Prerequisites

• Docker (with BuildKit support)
• NVIDIA Docker Runtime (for GPU support)
• NVIDIA GPU with CUDA support (optional, will fall back to CPU)

Installing NVIDIA Container Toolkit

# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

Quick Start

Build the Docker Image

# Build the image
docker build -t ultralytics-app:latest .

# Build with build arguments (optional)
docker build \
  --build-arg CUDA_VERSION=12.6.0 \
  -t ultralytics-app:latest .

Run the Application

With GPU support:

docker run --gpus all --rm ultralytics-app:latest

CPU only:

docker run --rm ultralytics-app:latest

Interactive mode:

docker run --gpus all -it --rm ultralytics-app:latest bash

Mount volumes for data/models:

docker run --gpus all --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/models:/app/models \
  ultralytics-app:latest

Development

Local Development with UV

Install UV package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create virtual environment and install dependencies:

# Create virtual environment
uv venv --python 3.13

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# Install dependencies
uv pip install -r pyproject.toml

Run the application locally:

python main.py

Adding Dependencies

Edit pyproject.toml and rebuild:

[project]
dependencies = [
    "ultralytics>=8.3.0",
    "torch>=2.0.0",
    "your-package>=1.0.0",  # Add here
]

Docker Image Optimization

This setup achieves minimal image size through:

1. Multi-stage builds: Separates build and runtime stages
2. UV package manager: Faster dependency resolution and installation
3. Minimal base image: Uses CUDA runtime (not devel) image
4. Efficient caching: Optimized layer ordering
5. .dockerignore: Excludes unnecessary files from build context
6. No cache storage: Removes package manager caches
7. Runtime-only deps: Only includes necessary runtime libraries

Image Size Comparison

Typical image sizes:

• With optimization: ~4-5 GB (CUDA runtime + Python + dependencies)
• Without optimization: ~8-10 GB

GPU Verification

To verify GPU is working inside the container:

docker run --gpus all --rm ultralytics-app:latest python -c "
import torch
print(f'CUDA Available: {torch.cuda.is_available()}')
print(f'CUDA Device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"N/A\"}')
"

Usage Examples

Object Detection on an Image

from ultralytics import YOLO

# Load model
model = YOLO('yolov8n.pt')

# Run inference
results = model.predict('image.jpg', save=True)

# Process results
for result in results:
    boxes = result.boxes
    for box in boxes:
        print(f"Class: {box.cls}, Confidence: {box.conf}")

Training a Model

from ultralytics import YOLO

# Load a model
model = YOLO('yolov8n.pt')

# Train the model
results = model.train(data='coco128.yaml', epochs=100, imgsz=640)

Environment Variables

Configure the application using environment variables:

docker run --gpus all --rm \
  -e YOLO_CONFIG_DIR=/app/.config/ultralytics \
  ultralytics-app:latest

Troubleshooting

GPU Not Detected

1. Verify NVIDIA drivers: nvidia-smi
2. Check Docker GPU support: docker run --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi
3. Ensure nvidia-container-toolkit is installed

Out of Memory Errors

Reduce batch size or image size:

results = model.predict('image.jpg', imgsz=320)  # Smaller image size

Slow First Run

The first run downloads YOLO models (~6-400MB depending on model). Subsequent runs use cached models.

Performance Tips

1. Use GPU: Always use --gpus all flag for significant speedup
2. Batch Processing: Process multiple images in batches
3. Model Selection: Choose appropriate model size (n/s/m/l/x)
4. Image Size: Use smaller image sizes for faster inference
5. FP16 Inference: Enable half-precision for 2x speedup

License

This project configuration is provided as-is. Ultralytics YOLO is licensed under AGPL-3.0.

Resources

• Ultralytics Documentation
• UV Documentation
• NVIDIA Docker Documentation
• CUDA Docker Images