docs/en/yolov5/environments/docker-image-quickstart-tutorial.md
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 <a href="https://colab.research.google.com/github/ultralytics/yolov5/blob/master/tutorial.ipynb"></a> <a href="https://www.kaggle.com/models/ultralytics/yolov5"></a>, GCP Deep Learning VM, or Amazon AWS guides. For a general overview of Docker usage with Ultralytics models, see the Ultralytics Docker Quickstart Guide.
Before you begin, ensure you have the following installed:
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 and RHEL-based systems like Fedora/CentOS, but refer to the official guide linked above for instructions specific to your distribution:
=== "Ubuntu/Debian"
```bash
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 the package lists and install the NVIDIA Container Toolkit:
```bash
sudo apt-get update
```
```bash
sudo apt-get install -y nvidia-container-toolkit
```
=== "RHEL/CentOS/Fedora/Amazon Linux"
```bash
curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \
| sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo
```
```bash
sudo dnf install -y nvidia-container-toolkit
```
Run nvidia-ctk cdi list to ensure the GPU CDI devices are available (the toolkit's nvidia-cdi-refresh service generates and maintains the spec automatically on toolkit >= 1.18):
nvidia-ctk cdi list
You should see entries such as nvidia.com/gpu=0 and nvidia.com/gpu=all. On Linux, CDI device requests require Docker >= 28.2.0 and NVIDIA Container Toolkit >= 1.18. The legacy --gpus all flag can lose GPU access after host daemon reloads, so upgrade older Linux hosts and use --device instead.
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.
Once the image is pulled, you can run it as a container.
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
To enable GPU access within the container, use the --device nvidia.com/gpu=... CDI flag. This requires the NVIDIA Container Toolkit to be installed correctly.
# Run with access to all available GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all $t
# Run with access to specific GPUs (e.g., GPUs 2 and 3)
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 $t
Refer to the Docker run reference for more details on command options.
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 --device nvidia.com/gpu=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).
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
See the Train Custom Data and Model Export tutorials for detailed usage.
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.
<p align="center"></p>You have successfully set up and run YOLOv5 within a Docker container.
--ipc=host needed?PyTorch dataloader workers share tensors through shared memory, and the Docker default of 64 MB is too small. --ipc=host shares the host's memory segment; --shm-size=8g is an alternative if you prefer to keep the container isolated.
Run nvidia-smi on the host to confirm the driver works, verify the NVIDIA Container Toolkit is installed with nvidia-ctk cdi list, and make sure Docker is 28.2 or newer so --device nvidia.com/gpu=all is accepted.
Mount host directories with -v /path/on/host:/path/in/container and point --data and --project at the mounted paths. Files written elsewhere inside the container are discarded when it is removed.
--view-img windows from inside the container?Yes, but the container needs access to a display server. See the X11 and Wayland instructions in the Ultralytics Docker guide. Without a display, save results with --save-txt or the default runs/detect/ output instead.