Docker容器内运行Qt5 C++ GUI程序报错的解决方案求助

Hey there, let’s tackle this Qt GUI in Docker problem you’re facing. I’ve run into similar issues with X11 forwarding over SSH and Docker, so here’s a breakdown of what’s going wrong and how to fix it without modifying the remote system:

Core Problems #

Your main hurdles are:

1. Missing low-level dependencies for Qt’s xcb plugin (even though the plugin is found, it can’t load without these).
2. Docker containers lack proper permissions to access the remote SSH session’s X11 display server.
3. Incorrect handling of the DISPLAY variable and X11 authentication in remote SSH scenarios.

Step 1: Ensure Full Qt XCB Dependencies in Your Docker Image #

First, make sure your Dockerfile installs all required libraries for the xcb plugin. For Debian/Ubuntu-based images, add this:

RUN apt-get update && apt-get install -y \
    libxcb1-dev \
    libxcb-keysyms1-dev \
    libxcb-image0-dev \
    libxcb-shm0-dev \
    libxcb-icccm4-dev \
    libxcb-sync0-dev \
    libxcb-xfixes0-dev \
    libxcb-shape0-dev \
    libxcb-randr0-dev \
    libxcb-render-util0-dev \
    libxcb-xinerama0-dev \
    libxcb-xkb-dev \
    libxkbcommon-dev \
    libxkbcommon-x11-dev \
    && rm -rf /var/lib/apt/lists/*

This fixes the "plugin found but not loadable" error by installing all underlying xcb dependencies.

Step 2: Properly Pass X11 Access to the Container (SSH Remote Scenario) #

Since you’re using SSH with X11 forwarding, we need to safely pass the display access without modifying the remote system’s sshd_config. Here are two reliable methods:

Method 1: Use Host Network (Simplest) #

This lets the container share the host’s network stack, making it easy to access the X11 forwarding port:

# Temporarily allow root (container's default user) to access the X server
xhost +local:root

# Run the container with proper X11 mounts and variables
docker run --rm -it \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v $HOME/.Xauthority:/root/.Xauthority \
    --net=host \
    my_image

• --net=host: Bypasses Docker’s network isolation so the container can reach the remote machine’s localhost X11 port.
• Sharing .Xauthority: Gives the container’s program permission to connect to the X server (no need to modify SSH config).
• xhost +local:root: Safer than xhost + since it only allows local root users to access the X server.

Method 2: Isolated Network (More Secure) #

If you don’t want to use host network, replace the localhost in your DISPLAY variable with the remote machine’s local IP:

# Get the remote machine's local IP (adjust interface if needed)
HOST_IP=$(hostname -I | awk '{print $1}')

# Allow this IP to access the X server
xhost +$HOST_IP

# Run the container with updated DISPLAY
docker run --rm -it \
    -e DISPLAY=$HOST_IP:$(echo $DISPLAY | cut -d: -f2) \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v $HOME/.Xauthority:/root/.Xauthority \
    my_image

This keeps the container network isolated while still letting it reach the X server.

Step 3: Test X11 Connectivity First #

Before running your Qt app, verify X11 works in the container with a simple tool like xeyes:

# Install x11-apps in the container (add this to your Dockerfile if needed)
apt-get update && apt-get install -y x11-apps

# Run the test
xeyes

If xeyes displays correctly, your X11 setup is good—any remaining issues are with your Qt app’s configuration (not the Docker/X11 setup).

Why Your Previous Attempts Failed #

Let’s quickly recap why your earlier methods didn’t work:

• Method 1: No Xauthority mount, so Qt lacked permission to connect to the X server.
• Method 2: Changing X11UseLocalhost no exposed X11 to the network, but you didn’t share Xauthority and the container couldn’t reach 127.0.1.1 due to network isolation.
• Method 3: Using :0 is only valid for local displays—remote SSH uses a different display number like localhost:10.0.
• Method 4: Creating a non-root user didn’t fix the X11 permission issue (you still needed to share Xauthority and update xhost).

Give these steps a try—they should resolve your Qt GUI Docker issue without modifying the remote system. If you still hit snags, check that the container’s echo $DISPLAY matches the remote machine’s, and that the .Xauthority file is properly mounted.

内容的提问来源于stack exchange，提问作者Aziuth