Windows11下Docker部署PyQt5 GUI报xcb无法连接$DISPLAY错误

当前配置完全复用了Linux宿主机运行PyQt GUI容器的逻辑，在Windows 11环境下存在三个核心问题：

1. Windows 11没有原生内置X11显示服务，直接挂载Linux的/tmp/.X11-unix套接字、传递Linux格式的$DISPLAY变量，容器根本找不到可用的显示端点
2. Dockerfile内缺少Qt xcb插件依赖的系统运行库，即使显示连接正常也会加载插件失败
3. 启动命令语法错误，未指定要运行的容器镜像，Docker会默认把python3识别为镜像名拉取，根本不会运行本地构建的项目镜像

1. 宿主机安装配置X11服务端 #

Windows下运行Linux GUI容器需要单独安装X Server负责接收容器的GUI渲染请求并显示窗口：

• 安装VcXsrv
• 启动XLaunch配置向导，按以下参数设置：
  • 显示模式选择 Multiple windows，显示编号填0，进入下一步
  • 客户端启动模式选择 Start no client，进入下一步
  • 额外参数勾选 Disable access control（允许Docker容器的连接请求），其余保持默认，点击完成启动服务
• 打开Windows防火墙设置，给VcXsrv放通专用、公用网络的入站访问权限，避免连接被拦截

2. 修正Dockerfile配置 #

补全xcb插件依赖的系统库，修正后的Dockerfile内容如下：

FROM ubuntu:20.04

ENV DEBIAN_FRONTEND=noninteractive
ENV LIBGL_ALWAYS_INDIRECT=1
# 关闭MIT共享内存扩展，适配跨环境X11连接
ENV QT_X11_NO_MITSHM=1

RUN adduser --quiet --disabled-password pyqt_user && usermod -a -G audio pyqt_user
# 补全Qt xcb插件依赖的所有系统运行库
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    python3-pyqt5 \
    libxkbcommon-x11-0 \
    libxcb-icccm4 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-randr0 \
    libxcb-render-util0 \
    libxcb-xinerama0 \
    libxcb-xkb1 \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# 配置默认启动用户和启动命令
USER pyqt_user
CMD ["python3", "main.py"]

修改完成后重新构建镜像：

docker build -t pyqt-app .

3. 修正容器启动命令 #

Windows环境下不需要挂载Linux的X11 unix套接字，DISPLAY变量需要指向宿主机的X Server地址，使用Docker内置的host.docker.internal域名即可直接访问宿主机服务，正确启动命令如下：

docker run --rm -it -e DISPLAY=host.docker.internal:0.0 pyqt-app

• 如果还是提示连接display失败，先确认VcXsrv已经正常启动（任务栏托盘能看到X图标），再临时关闭Windows Defender防火墙测试是否是防火墙拦截导致
• 如果提示xcb插件加载失败，进入容器执行ldd /usr/lib/x86_64-linux-gnu/qt5/plugins/platforms/libqxcb.so，查看输出中是否有not found标记的依赖库，对应补装即可
• 如果使用WSL2后端的Docker Desktop，确认WSL2实例内能够连通host.docker.internal，如果不通可以在启动命令中额外添加--add-host=host.docker.internal:host-gateway参数

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