ultralytics/docs/en/yolov5/environments/docker_image_quickstart_tutorial.md

comments	description	keywords
true	Learn how to set up and run YOLOv5 in a Docker container with step-by-step instructions for CPU and GPU environments, mounting volumes, and using display servers.	YOLOv5, Docker, Ultralytics, setup, guide, tutorial, machine learning, deep learning, AI, GPU, NVIDIA, container, X11, Wayland

Get Started with YOLOv5 🚀 in Docker

Welcome to the Ultralytics YOLOv5 Docker Quickstart Guide! This tutorial provides step-by-step instructions for setting up and running YOLOv5 within a Docker container. Using Docker enables you to run YOLOv5 in an isolated, consistent environment, simplifying deployment and dependency management across different systems. This approach leverages containerization to package the application and its dependencies together.

For alternative setup methods, consider our Colab Notebook , GCP Deep Learning VM, or Amazon AWS guides. For a general overview of Docker usage with Ultralytics models, see the Ultralytics Docker Quickstart Guide.

Prerequisites

Before you begin, ensure you have the following installed:

1. Docker: Download and install Docker from the official Docker website. Docker is essential for creating and managing containers.
2. NVIDIA Drivers (Required for GPU support): Ensure you have NVIDIA drivers version 455.23 or higher installed. You can download the latest drivers from NVIDIA's website.
3. NVIDIA Container Toolkit (Required for GPU support): This toolkit allows Docker containers to access your host machine's NVIDIA GPUs. Follow the official NVIDIA Container Toolkit installation guide for detailed instructions.

Setting up NVIDIA Container Toolkit (GPU Users)

First, verify that your NVIDIA drivers are installed correctly by running:

nvidia-smi

This command should display information about your GPU(s) and the installed driver version.

Next, install the NVIDIA Container Toolkit. The commands below are typical for Debian-based systems like Ubuntu, but refer to the official guide linked above for instructions specific to your distribution:

# Add NVIDIA package repositories (refer to official guide for latest setup)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Update package list and install the toolkit
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Configure Docker to use the NVIDIA runtime
sudo nvidia-ctk runtime configure --runtime=docker

# Restart Docker service to apply changes
sudo systemctl restart docker

Finally, verify that the NVIDIA runtime is configured and available to Docker:

docker info | grep -i runtime

You should see nvidia listed as one of the available runtimes.

Step 1: Pull the YOLOv5 Docker Image

Ultralytics provides official YOLOv5 images on Docker Hub. The latest tag tracks the most recent repository commit, ensuring you always get the newest version. Pull the image using the following command:

# Define the image name with tag
t=ultralytics/yolov5:latest

# Pull the latest YOLOv5 image from Docker Hub
sudo docker pull $t

You can browse all available images at the Ultralytics YOLOv5 Docker Hub repository.

Step 2: Run the Docker Container

Once the image is pulled, you can run it as a container.

Using CPU Only

To run an interactive container instance using only the CPU, use the -it flag. The --ipc=host flag allows sharing of host IPC namespace, which is important for shared memory access.

# Run an interactive container instance using CPU
sudo docker run -it --ipc=host $t

Using GPU

To enable GPU access within the container, use the --gpus flag. This requires the NVIDIA Container Toolkit to be installed correctly.

# Run with access to all available GPUs
sudo docker run -it --ipc=host --gpus all $t

# Run with access to specific GPUs (e.g., GPUs 2 and 3)
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t

Refer to the Docker run reference for more details on command options.

Mounting Local Directories

To work with your local files (datasets, model weights, etc.) inside the container, use the -v flag to mount a host directory into the container:

# Mount /path/on/host (your local machine) to /path/in/container (inside the container)
sudo docker run -it --ipc=host --gpus all -v /path/on/host:/path/in/container $t

Replace /path/on/host with the actual path on your machine and /path/in/container with the desired path inside the Docker container (e.g., /usr/src/datasets).

Step 3: Use YOLOv5 🚀 within the Docker Container

You are now inside the running YOLOv5 Docker container! From here, you can execute standard YOLOv5 commands for various Machine Learning and Deep Learning tasks like Object Detection.

# Train a YOLOv5 model on your custom dataset (ensure data is mounted or downloaded)
python train.py --data your_dataset.yaml --weights yolov5s.pt --img 640 # Start training

# Validate the trained model's performance (Precision, Recall, mAP)
python val.py --weights path/to/your/best.pt --data your_dataset.yaml # Validate accuracy

# Run inference on images or videos using a trained model
python detect.py --weights yolov5s.pt --source path/to/your/images_or_videos # Perform detection

# Export the trained model to various formats like ONNX, CoreML, or TFLite for deployment
python export.py --weights yolov5s.pt --include onnx coreml tflite # Export model

Explore the documentation for detailed usage of different modes:

• Train
• Validate
• Predict
• Export

Learn more about evaluation metrics like Precision, Recall, and mAP. Understand different export formats like ONNX, CoreML, and TFLite, and explore various Model Deployment Options. Remember to manage your model weights effectively.

Congratulations! You have successfully set up and run YOLOv5 within a Docker container.