Docker Quickstart Guide for Ultralytics
This guide shows how to set up a Docker environment for your Ultralytics projects. Docker is a platform for developing, shipping, and running applications in containers, which ensures that the software runs the same regardless of where it's deployed.
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
Watch: How to Get started with Docker | Usage of Ultralytics Python Package inside Docker live demo ๐
Prerequisites#
- 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.
Setting up Docker with NVIDIA Support (Optional)#
First, verify that the NVIDIA drivers are properly installed by running:
nvidia-smiInstalling NVIDIA Container Toolkit#
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.listUpdate the package lists and install the NVIDIA Container Toolkit:
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitVerify 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 listYou should see entries such as nvidia.com/gpu=0 and nvidia.com/gpu=all. Discovered CDI devices also appear in docker info.
Installing Ultralytics Docker Images#
Ultralytics publishes the following images to Docker Hub. Each image is built from its linked Dockerfile by the Docker publishing workflow.
| Tag | Platform and purpose | Source |
|---|---|---|
latest | Linux AMD64 with CUDA for GPU training and inference | Dockerfile |
latest-export | Linux AMD64 with CUDA and export dependencies for conversion and benchmarking | Dockerfile-export |
latest-amd | Linux AMD64 with ROCm and MIGraphX for AMD GPU training and inference | Dockerfile-amd |
latest-python | Lightweight Linux AMD64 Python 3.14 image for CPU inference | Dockerfile-python |
latest-python-export | Linux AMD64 Python 3.13 CPU image with export dependencies | Dockerfile-python-export |
latest-cpu | Linux AMD64 CPU image with Bash as the default command | Dockerfile-cpu |
latest-jupyter | Linux AMD64 CPU image with JupyterLab and Ultralytics tutorial notebooks | Dockerfile-jupyter |
latest-arm64 | Linux ARM64 Python 3.13 CPU image for Apple silicon, Raspberry Pi, and other ARM64 systems | Dockerfile-arm64 |
latest-nvidia-arm64 | Linux ARM64 for DGX Spark (DGX OS) and PyTorch on Thor (JetPack 7.1); bundled TensorRT does not support JetPack | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | Linux ARM64 for NVIDIA Jetson devices running JetPack 6 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | Linux ARM64 for NVIDIA Jetson devices running JetPack 5 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | Linux ARM64 for NVIDIA Jetson devices running JetPack 4 | Dockerfile-jetson-jetpack4 |
latest-runner | Linux AMD64 CUDA image for a self-hosted GitHub Actions GPU runner | Dockerfile-runner |
latest-runner-cpu | Linux AMD64 image for a self-hosted GitHub Actions CPU runner | Dockerfile-runner-cpu |
The AMD64 GPU images (latest, latest-export, and latest-runner) use PyTorch 2.15 and CUDA 13.2. Check the host driver's CUDA support with nvidia-smi before launching them; installing a newer container does not upgrade the host driver. CUDA 13 removes support for Maxwell, Pascal, and Volta GPUs, including Tesla P100 and V100.
The NVIDIA ARM64 image uses NVIDIA PyTorch 26.10 with CUDA 13.4 and TensorRT 11.4. Its PyTorch support for Thor does not extend to TensorRT: NVIDIA does not support TensorRT 11.4 on JetPack. For Jetson TensorRT exports, use the supported TensorRT 10.x runtime for your JetPack release. Follow the platform requirements in the Jetson guide or DGX Spark guide. The JetPack 4, 5, and 6 images retain their separate device-specific stacks.
The Conda Dockerfile is available for local builds; automated publishing of latest-conda is disabled, so that registry tag does not contain these updates.
The Python, CPU, Jupyter, and CPU runner images use Python 3.14. The Python export image uses the latest-python-3.13 base, built from the same Dockerfile-python with --build-arg PYTHON_VERSION=3.13, because TensorFlow, CoreML, and PaddlePaddle do not support Python 3.14 yet.
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:latestTo build an image yourself instead, clone the repository and pass the matching Dockerfile from the table above, using the repository root as the build context:
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .Running Ultralytics in Docker Container#
Here's how to run the Ultralytics Docker container:
Using only the CPU#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuUsing 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:latestThe -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. For NVIDIA GPUs, the --device nvidia.com/gpu=... flag grants access through CDI. For AMD GPUs, the --device flags grant access to the GPU kernel driver (/dev/kfd) and display render nodes (/dev/dri).
On Linux, CDI device requests require Docker >= 28.2.0 (CDI enabled by default) and nvidia-container-toolkit >= 1.18 (automatic CDI spec generation). Upgrade older Linux hosts before running GPU containers. The legacy --gpus all flag can lose GPU access (Failed to initialize NVML: Unknown Error) when the host reloads systemd during routine package updates (nvidia-container-toolkit#48). CDI --device requests include the device nodes in the container configuration, so long-running containers such as training workers or CI runners keep GPU access across reloads.
Docker Desktop GPU support on Windows currently uses --gpus all with the WSL 2 backend because NVIDIA CDI devices are not available there. Windows does not use Linux systemd, so the daemon-reload failure above does not apply.
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 --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestReplace /path/on/host with the directory path on your local machine and /path/in/container with the desired path inside the Docker container.
Persisting 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/runsThis saves all training outputs to ./runs on your host machine.
Run graphical user interface (GUI) applications in a Docker Container#
The following instructions are experimental. Sharing an X11 socket with a Docker container poses potential security risks. Therefore, it's recommended to test this solution only in a controlled environment.
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#
Use GPUs
If you're using GPUs, you can add the --device nvidia.com/gpu=all flag to the command.
If you're using X11, you can run the following command to allow the Docker container to access the X11 socket:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.Xauthority:/root/.Xauthority \
-it --ipc=host ultralytics/ultralytics:latestThis command sets the DISPLAY environment variable to the host's display, mounts the X11 socket, and maps the .Xauthority file to the container. The xhost +local:docker command allows the Docker container to access the X11 server.
Using Docker with a GUI#
Ultralytics images ship headless OpenCV, so first install the GUI build of OpenCV and its system libraries inside the container:
apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libsm6
pip uninstall -y opencv-python-headless && pip install opencv-pythonNow 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=TrueTesting
A simple way to validate that the Docker group has access to the X11 server is to run a container with a GUI program like xclock or xeyes. Alternatively, you can also install these programs in the Ultralytics Docker container to test the access to the X11 server of your GNU/Linux display server. If you run into any problems, consider setting the environment variable -e QT_DEBUG_PLUGINS=1. Setting this environment variable enables the output of debugging information, aiding in the troubleshooting process.
When finished with Docker GUI#
In both cases, don't forget to revoke access from the Docker group when you're done.
xhost -local:dockerWant to view image results directly in the Terminal?
On Linux and macOS, you can display image results in the VSCode integrated terminal using the sixel protocol.
You are now set up to use Ultralytics with Docker. To self-host the Ultralytics web application, see the Platform On-Premise guide.
FAQ#
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:latestUsing 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 keeping model deployments reproducible. Use
latestfor general NVIDIA GPU training or select the image matching your JetPack version for an NVIDIA Jetson device.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 GPUsThis command sets up a Docker container with GPU access, which you can limit to specific GPUs or switch to AMD ROCm.
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:latestFor 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:latestInside the container, install the GUI build of OpenCV before using
show=True, as described in the Run graphical user interface (GUI) applications in a Docker Container section.Yes, you can mount local directories into the Ultralytics Docker container using the
-vflag:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latestReplace
/path/on/hostwith the directory on your local machine and/path/in/containerwith 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.
Comments14
Ask a question, share your results, or help someone else.
Letรญcia RamaHello,
Is this workflow suitable for other YOLO families, such as YOLO26?
Glenn JocherUltralyticsYes, the same workflow supports YOLO26 and other model families available in the
ultralyticspackageโuse an up-to-date official image and specify the appropriate weights, such asmodel=yolo26n.pt. See the Docker Quickstart Guide for current image options, and feel free to drop any follow-up questions here so the Ultralytics team can help.1
Letรญcia RamaRight Glenn, thanks
lauravchrobak
It looks like the, "Running Ultralytics in Docker Container" section is duplicated here
HellaPinot
Hello! I have been testing running yolov8 inside a container, things seem to work well however after a somewhat random amount of time the inference hangs with no error output.
I know the container hasn't crashed as I am reading events from a processing queue and I can see new partitions are being allocated on another thread.
I'm running two models one after the other (different sizes and detection classes), so I'm wondering if this could be the root of the issue? At no point would they be running at the same time.
I believe it is happening exactly when I call predict. Its hard to debug as again it happens very randomly and there is not output from the container, it seems like there might be an infinite loop somewhere thats stopping it from continuing.
Curious if anything like this has been encountered before?
Glenn JocherUltralyticsHello! ๐
It sounds like a tricky issue, especially since it occurs randomly. Here are a few suggestions that might help you isolate or resolve the problem:
-
Logging and Monitoring: Enhance the logging within your container. Consider logging the input sizes and other relevant data before the prediction call, and make sure you're logging any exceptions that could be silently caught.
-
Resource Checks: Ensure that there are no resource starvation issues, such as GPU memory not being freed up properly. Tools like
nvidia-smican help monitor GPU usage. -
Sequential Model Loading: Although the models are run sequentially and not in parallel, it could be beneficial to explicitly clear the memory after each model's predictions are done. This can be done by deleting model objects and calling
torch.cuda.empty_cache()if you are using PyTorch. -
Hardware Testing: Run your container pointing the inference to CPU only for a time to see if the problem persists. This could help determine if the issue is related to GPU computation or not.
-
Reproducibility Tactic: Since the issue is sporadic, try to determine if thereโs a specific type of input or specific conditions under which this occurs more frequently.
If these suggestions don't help, please provide more details or code snippets, and Iโd be happy to dive deeper into this!
Let me know how it goes!
-
HWKevinhwk
I want to install ultralytics using docker on top of NVIDIA TX2, is there a detailed procedure? The reason for this question is that after entering the command nvidia-smi in the TX2 terminal, the output is command not found, and I'm worried that the steps in the document above are not applicable to TX2.
Paula DerrengerUltralytics(edited)@HWKevinhwk hey there! ๐ Setting up Ultralytics on NVIDIA TX2 with Docker can be a bit tricky if
nvidia-smiis missing, but no worries.For NVIDIA Jetson platforms like TX2,
nvidia-smiis typically not available, and you'll usetegrastatsinstead to monitor the GPU. The Jetson TX2 is supported on JetPack 4, so install JetPack 4 first, as it includes the NVIDIA drivers and libraries needed for GPU acceleration. Jetson devices use the Docker integration provided through JetPack with--runtime=nvidiarather than--gpus all. Then pull and run the Ultralytics Docker image for JetPack 4:t=ultralytics/ultralytics:latest-jetson-jetpack4 sudo docker pull $t && sudo docker run -it --ipc=host --runtime=nvidia $tSee the NVIDIA Jetson guide for details. If you encounter any specific issues, feel free to drop them here. Happy detecting! ๐
HWKevinhwk
Is there a detailed tutorial on deploying yolov8 on jetson TX2 using docker? I am pulling images docker pull ultralytics/ultralytics:latest-jetson terminal will downloading pause, long time pulling images unsuccessful, repeated attempts still so, any solution please?
Paula DerrengerUltralytics(edited)@HWKevinhwk hey there! ๐
It sounds like you're facing issues with the Docker image pull for the Jetson TX2. This might be due to network issues or Docker Hub delays, or to using a tag that does not exist.
Here's a simplified breakdown to get you started on the TX2 using Docker:
-
Ensure JetPack is installed: The TX2 is supported on JetPack 4, which includes the GPU drivers necessary for Docker integration with the Jetson GPU.
-
Install Docker:
sudo apt-get install docker.io -
NVIDIA runtime support (JetPack should handle this):
nvidia-smidoesn't work on Jetson, so verify thenvidiaruntime withdocker info | grep -i runtime. -
Pull the Docker image for Jetson. Pulling large Docker images can be challenging on slower networks:
sudo docker pull ultralytics/ultralytics:latest-jetson-jetpack4If you keep facing issues while pulling the image, try restarting your Docker service or check your network settings. Sometimes, using a different network can help too!
-
Run the Image:
sudo docker run -it --ipc=host --runtime=nvidia ultralytics/ultralytics:latest-jetson-jetpack4
This should set you on the right path to running Ultralytics YOLO on your Jetson TX2. If the problem persists, it might be worth checking Docker's log or discussing this issue further with your network admin or on Docker forums! ๐
Happy coding! ๐
-
Peter-coding
Hey! I trained a YOLOv8 model on my local computer. I have the best.pt file, and I can use it in CLI (conda) for predict. I want to make a python app, which uses this best.pt file, and I want to containerize it. Is it possible to write the full python app (it is just a few lines of code, which runs the detection, then writes the detection result to a database), then containerize it, and able to use it anywhere? Thank you! :D
Paula DerrengerUltralyticsHey there! ๐
Absolutely, you can absolutely containerize your Python app that uses the
best.ptmodel! Here's a quick guide:-
Create Your Python App: Just like you mentioned, write your Python code that performs the detection and interacts with the database.
-
Dockerize Your Application:
-
Dockerfile: Create a Dockerfile in your project directory. Here's a simple example that uses Ultralytics' Docker image as a base:
FROM ultralytics/ultralytics:latest WORKDIR /app COPY . /app RUN pip install -r requirements.txt # Assuming you have a requirements.txt CMD ["python", "your_script.py"] -
Build Your Docker Image: Run the following command in your project directory:
sudo docker build -t your-app-name . -
Run Your Container: To run your container, especially if you're planning to use GPU, you might want to specify
--gpus all:sudo docker run -it --ipc=host --gpus all your-app-nameFor accessing local files, consider mounting a volume as described in the Docker Quickstart Guide.
-
-
Deployment: With your Docker image built, you can now deploy and run it anywhere that Docker is supported. If using a GPU, ensure the host machine supports NVIDIA GPUs and has the necessary drivers and Docker configured correctly.
That's it! You should be able to use your model within a containerized app now. If you hit any snags, double-check the Docker Quickstart Guide for Ultralytics for more details. Happy coding! ๐
-
udayzee05
DEPRECATION NOTICE The nvidia-docker wrapper is no longer supported, and the NVIDIA Container Toolkit has been extended to allow users to configure Docker to use the NVIDIA Container Runtime. For further instructions, see the NVIDIA Container Toolkit documentation and specifically the install guide.22 Jan 2024
Paula DerrengerUltralytics(edited)Hey there! ๐ Thanks for bringing up the deprecation notice regarding the nvidia-docker wrapper. You're right; use the NVIDIA Container Toolkit for GPU support in Docker containers. Here's how to set it up on Ubuntu/Debian, as described in our Docker Quickstart Guide:
# Add the NVIDIA Container Toolkit repository 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 # Install the NVIDIA Container Toolkit sudo apt-get update sudo apt-get install -y nvidia-container-toolkitAnd to verify that the GPU devices are available to Docker:
nvidia-ctk cdi listThis should list entries such as
nvidia.com/gpu=all, indicating that your Docker setup can leverage GPU acceleration. ๐For more detailed instructions and tips on using Ultralytics with Docker, including mounting local directories and running containers, check out our Docker Quickstart Guide. Happy coding!