Enable GUI Visualization on Docker with X11 Forwarding (#11729)

Co-authored-by: Glenn Jocher <glenn.jocher@ultralytics.com>
Co-authored-by: Gereziher Adhane <gereziherw@gmail.com>
Co-authored-by: Francesco Mattioli <Francesco.mttl@gmail.com>
Co-authored-by: Burhan <62214284+Burhan-Q@users.noreply.github.com>

docker/Dockerfile

@@ -13,8 +13,9 @@ ADD https://github.com/ultralytics/assets/releases/download/v0.0.0/Arial.ttf \
 
 # Install linux packages
 # g++ required to build 'tflite_support' and 'lap' packages, libusb-1.0-0 required for 'tflite_support' package
+# libsm6 required by libqxcb to create QT-based windows for visualization; set 'QT_DEBUG_PLUGINS=1' to test in docker
 RUN apt update \
-    && apt install --no-install-recommends -y gcc git zip curl htop libgl1 libglib2.0-0 libpython3-dev gnupg g++ libusb-1.0-0
+    && apt install --no-install-recommends -y gcc git zip curl htop libgl1 libglib2.0-0 libpython3-dev gnupg g++ libusb-1.0-0 libsm6
 
 # Security updates
 # https://security.snyk.io/vuln/SNYK-UBUNTU1804-OPENSSL-3314796

docs/en/guides/docker-quickstart.md

@@ -18,7 +18,8 @@ This guide serves as a comprehensive introduction to setting up a Docker environ
 
 - Setting up Docker with NVIDIA support
 - Installing Ultralytics Docker images
-- Running Ultralytics in a Docker container
+- 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
 
 ---
@@ -92,6 +93,35 @@ sudo docker pull $t
 ## Running Ultralytics in Docker Container
 
 Here's how to execute the Ultralytics Docker container:
+### Using only the CPU
+```bash
+# Run with all GPUs
+sudo docker run -it --ipc=host $t
+```
+### Using GPUs
+```bash
+# 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
+
+```bash
+# Run with all GPUs
+sudo docker run -it --ipc=host $t
+```
+
+### Using GPUs
 
 ```bash
 # Run with all GPUs
@@ -114,6 +144,79 @@ 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
+
+!!! danger "Highly Experimental - User Assumes All Risk"
+
+    The following instructions are experimental. Sharing a X11 socket with a Docker container poses potential security risks. Therefore, it's recommended to test this solution only in a controlled environment. For more information, refer to these resources on how to use `xhost`<sup>[(1)](http://users.stat.umn.edu/~geyer/secure.html)[(2)](https://linux.die.net/man/1/xhost)</sup>.
+
+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](https://www.x.org/wiki/) (also known as the X Window System) and [Wayland](https://wayland.freedesktop.org/). Before starting it's essential to determine which graphics server you're currently using. Just run this command to find out:
+
+```bash
+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
+
+!!! example
+
+    ??? info "Use GPUs"
+            If you're using [GPUs](#using-gpus), you can add the `--gpus all` flag to the command.
+
+    === "X11"
+
+        If you're using X11, you can run the following command to allow the Docker container to access the X11 socket:
+
+        ```bash
+        xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
+        -v /tmp/.X11-unix:/tmp/.X11-unix \
+        -v ~/.Xauthority:/root/.Xauthority \
+        -it --ipc=host $t
+        ```
+
+        This 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.
+
+
+    === "Wayland"
+
+        For Wayland, use the following command:
+
+        ```bash
+        xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
+        -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \
+        --net=host -it --ipc=host $t
+        ```
+
+        This command sets the `DISPLAY` environment variable to the host's display, mounts the Wayland socket, and allows the Docker container to access the Wayland server.
+
+### Using Docker with a GUI
+
+Now you can display graphical applications inside your Docker container. For example, you can run the following [CLI command](../usage/cli.md) to visualize the [predictions](../modes/predict.md) from a [YOLOv8 model](../models/yolov8.md):
+
+```bash
+yolo predict model=yolov8n.pt show=True
+```
+
+??? info "Testing"
+
+    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`](https://www.x.org/archive/X11R6.8.1/doc/xclock.1.html) or [`xeyes`](https://www.x.org/releases/X11R7.5/doc/man/man1/xeyes.1.html). 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
+
+!!! warning "Revoke access"
+
+    In both cases, don't forget to revoke access from the Docker group when you're done.
+
+    ```bash
+    xhost -local:docker
+    ```
+
+??? question "Want to view image results directly in the Terminal?"
+
+    Refer to the following guide on [viewing the image results using a terminal](./view-results-in-terminal.md)
+
 ---
 
 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](../quickstart.md).

ultralytics/utils/checks.py

@@ -535,7 +535,8 @@ def check_imshow(warn=False):
     """Check if environment supports image displays."""
     try:
         if LINUX:
-            assert "DISPLAY" in os.environ and not IS_DOCKER and not IS_COLAB and not IS_KAGGLE
+            assert not IS_COLAB and not IS_KAGGLE
+            assert "DISPLAY" in os.environ, "The DISPLAY environment variable isn't set."
         cv2.imshow("test", np.zeros((8, 8, 3), dtype=np.uint8))  # show a small 8-pixel image
         cv2.waitKey(1)
         cv2.destroyAllWindows()