Link to this sectionDocker 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.

Link to this sectionWhat 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

Link to this sectionPrerequisites#

• Make sure Docker is installed on your system. If not, you can download and install it from Docker's website.
• For GPU acceleration, ensure that your system has an NVIDIA GPU and NVIDIA drivers installed. CPU images do not require NVIDIA hardware.
• If you are using NVIDIA Jetson devices, ensure that you have the appropriate JetPack version installed. Refer to the NVIDIA Jetson guide for more details.

Link to this sectionSetting up Docker with NVIDIA Support (Optional)#

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

nvidia-smi

Link to this sectionInstalling NVIDIA Container Toolkit#

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

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

sudo apt-get update

sudo apt-get install -y nvidia-container-toolkit

Link to this sectionVerify CDI Devices with Docker#

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. Discovered CDI devices also appear in docker info.

Link to this sectionInstalling Ultralytics Docker Images#

Ultralytics publishes the following images to Docker Hub. Each image is built from its linked Dockerfile by the Docker publishing workflow.

Tags beginning with latest track the most recently published main-branch build. Versioned tags replace the latest prefix with an Ultralytics release, such as VERSION, VERSION-cpu, or VERSION-jetson-jetpack6. Use a versioned tag for a reproducible environment.

To pull the latest image:

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

Link to this sectionRunning Ultralytics in Docker Container#

Here's how to execute the Ultralytics Docker container:

Link to this sectionUsing only the CPU#

# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu

Link to this sectionUsing GPUs#

# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latest

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 --device nvidia.com/gpu=... flag grants the container access to the host's GPUs through CDI.

Link to this sectionNote 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 --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

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

Link to this sectionPersisting Training Outputs#

Training outputs save to /ultralytics/runs/<task>/<name>/ inside the container by default. Without mounting a host directory, outputs are lost when the container is removed.

To persist training outputs:

# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
  yolo train model=yolo26n.pt data=coco8.yaml project=/w/runs

This saves all training outputs to ./runs on your host machine.

Link to this sectionRun 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.

Link to this sectionRunning a Docker Container with a GUI#

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

Link to this sectionUsing 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 YOLO26 model:

yolo predict model=yolo26n.pt show=True

Link to this sectionWhen finished with Docker GUI#

xhost -local:docker

You are now set up to use Ultralytics with Docker and ready to take advantage of its capabilities. To self-host the Ultralytics web application, see the Platform On-Premise guide. For alternative Python package installation methods, see the Ultralytics quickstart documentation.

Link to this sectionFAQ#

Link to this sectionHow 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 Container Toolkit 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.

Link to this sectionWhat 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. Use latest for general NVIDIA GPU training or select the image matching your JetPack version for an NVIDIA Jetson device. See the complete image table or explore Ultralytics Docker Hub.

Link to this sectionHow can I run Ultralytics YOLO in a Docker container with GPU support?#

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

sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUs

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

Link to this sectionHow 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.

Link to this sectionCan 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 --device nvidia.com/gpu=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 Note on File Accessibility section.