Docker Quickstart Guide for Ultralytics

This guide serves as a comprehensive introduction to setting up a Docker environment for your Ultralytics projects. Docker is a platform for developing, shipping, and running applications in containers. It is particularly beneficial for ensuring that the software will always run the same, regardless of where it's deployed. For more details, visit the Ultralytics Docker repository on Docker Hub.

What You Will Learn

• Setting up Docker with NVIDIA support
• Installing Ultralytics Docker images
• Running Ultralytics in a Docker container with CPU or GPU support
• Using a Display Server with Docker to Show Ultralytics Detection Results
• Mounting local directories into the container

Prerequisites

• Make sure Docker is installed on your system. If not, you can download and install it from Docker's website.
• Ensure that your system has an NVIDIA GPU and NVIDIA drivers are installed.

Setting up Docker with NVIDIA Support

First, verify that the NVIDIA drivers are properly installed by running:

nvidia-smi

Installing NVIDIA Docker Runtime

Now, let's install the NVIDIA Docker runtime to enable GPU support in Docker containers:

# Add NVIDIA package repositories
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
distribution=$(lsb_release -cs)
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# Install NVIDIA Docker runtime
sudo apt-get update
sudo apt-get install -y nvidia-docker2

# Restart Docker service to apply changes
sudo systemctl restart docker

Verify NVIDIA Runtime with Docker

Run docker info | grep -i runtime to ensure that nvidia appears in the list of runtimes:

docker info | grep -i runtime

Installing Ultralytics Docker Images

Ultralytics offers several Docker images optimized for various platforms and use-cases:

• Dockerfile: GPU image, ideal for training.
• Dockerfile-arm64: For ARM64 architecture, suitable for devices like Raspberry Pi.
• Dockerfile-cpu: CPU-only version for inference and non-GPU environments.
• Dockerfile-jetson: Optimized for NVIDIA Jetson devices.
• Dockerfile-python: Minimal Python environment for lightweight applications.
• Dockerfile-conda: Includes Miniconda3 and Ultralytics package installed via Conda.

To pull the latest image:

# Set image name as a variable
t=ultralytics/ultralytics:latest

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

Running Ultralytics in Docker Container

Here's how to execute the Ultralytics Docker container:

Using only the CPU

# Run with all GPUs
sudo docker run -it --ipc=host $t

Using GPUs

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

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t

The -it flag assigns a pseudo-TTY and keeps stdin open, allowing you to interact with the container. The --ipc=host flag enables sharing of host's IPC namespace, essential for sharing memory between processes. The --gpus flag allows the container to access the host's GPUs.

Running Ultralytics in Docker Container

Here's how to execute the Ultralytics Docker container:

Using only the CPU

# Run with all GPUs
sudo docker run -it --ipc=host $t

Using GPUs

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

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t

The -it flag assigns a pseudo-TTY and keeps stdin open, allowing you to interact with the container. The --ipc=host flag enables sharing of host's IPC namespace, essential for sharing memory between processes. The --gpus flag allows the container to access the host's GPUs.

Note on File Accessibility

To work with files on your local machine within the container, you can use Docker volumes:

# Mount a local directory into the container
sudo docker run -it --ipc=host --gpus all -v /path/on/host:/path/in/container $t

Replace /path/on/host with the directory path on your local machine and /path/in/container with the desired path inside the Docker container.

Run graphical user interface (GUI) applications in a Docker Container

Docker is primarily used to containerize background applications and CLI programs, but it can also run graphical programs. In the Linux world, two main graphic servers handle graphical display: X11 (also known as the X Window System) and Wayland. Before starting, it's essential to determine which graphics server you are currently using. Run this command to find out:

env | grep -E -i 'x11|xorg|wayland'

Setup and configuration of an X11 or Wayland display server is outside the scope of this guide. If the above command returns nothing, then you'll need to start by getting either working for your system before continuing.

Running a Docker Container with a GUI

If you're using [GPUs](#using-gpus), you can add the `--gpus all` flag to the command.

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.Xauthority:/root/.Xauthority \
-it --ipc=host $t

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \
--net=host -it --ipc=host $t

Using Docker with a GUI

Now you can display graphical applications inside your Docker container. For example, you can run the following CLI command to visualize the predictions from a YOLOv8 model:

yolo predict model=yolov8n.pt show=True

When finished with Docker GUI

xhost -local:docker

Congratulations! You're now set up to use Ultralytics with Docker and ready to take advantage of its powerful capabilities. For alternate installation methods, feel free to explore the Ultralytics quickstart documentation.

FAQ

How do I set up Ultralytics with Docker?

To set up Ultralytics with Docker, first ensure that Docker is installed on your system. If you have an NVIDIA GPU, install the NVIDIA Docker runtime to enable GPU support. Then, pull the latest Ultralytics Docker image from Docker Hub using the following command:

sudo docker pull ultralytics/ultralytics:latest

For detailed steps, refer to our Docker Quickstart Guide.

What are the benefits of using Ultralytics Docker images for machine learning projects?

Using Ultralytics Docker images ensures a consistent environment across different machines, replicating the same software and dependencies. This is particularly useful for collaborating across teams, running models on various hardware, and maintaining reproducibility. For GPU-based training, Ultralytics provides optimized Docker images such as Dockerfile for general GPU usage and Dockerfile-jetson for NVIDIA Jetson devices. Explore Ultralytics Docker Hub for more details.

How can I run Ultralytics YOLO in a Docker container with GPU support?

First, ensure that the NVIDIA Docker runtime is installed and configured. Then, use the following command to run Ultralytics YOLO with GPU support:

sudo docker run -it --ipc=host --gpus all ultralytics/ultralytics:latest

This command sets up a Docker container with GPU access. For additional details, see the Docker Quickstart Guide.

How do I visualize YOLO prediction results in a Docker container with a display server?

To visualize YOLO prediction results with a GUI in a Docker container, you need to allow Docker to access your display server. For systems running X11, the command is:

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.Xauthority:/root/.Xauthority \
-it --ipc=host ultralytics/ultralytics:latest

For systems running Wayland, use:

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \
--net=host -it --ipc=host ultralytics/ultralytics:latest

More information can be found in the Run graphical user interface (GUI) applications in a Docker Container section.

Can I mount local directories into the Ultralytics Docker container?

Yes, you can mount local directories into the Ultralytics Docker container using the -v flag:

sudo docker run -it --ipc=host --gpus all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Replace /path/on/host with the directory on your local machine and /path/in/container with the desired path inside the container. This setup allows you to work with your local files within the container. For more information, refer to the relevant section on mounting local directories.

Comments