How to Troubleshoot `libxcb.so.1` Import Failures on Headless Servers with NVIDIA Cosmos

Install the missing X11 system libraries libxcb1, libgl1, and libglib2.0-0 using apt-get to resolve the ImportError: libxcb.so.1 when running NVIDIA Cosmos pipelines on headless Linux servers or Docker containers.

When deploying NVIDIA Cosmos video generation pipelines on cloud VMs or minimal Docker containers, you may encounter a frustrating ImportError: libxcb.so.1: cannot open shared object file immediately upon importing the Python modules. This error halts execution before any inference code runs, blocking both the Diffusers and Cosmos-Framework integration paths. According to the official NVIDIA Cosmos repository, this issue stems from missing X11 client libraries that are assumed present on desktop systems but absent in headless environments.

Why the libxcb.so.1 Error Occurs on Headless Systems

The Dependency Chain Behind the Error

The Cosmos pipelines rely on underlying graphics and vision libraries—specifically torch, opencv, and their X-window-related bindings—that dynamically link against X11 system libraries. On a workstation with a desktop environment, libxcb, libGL, and libglib are readily available. However, headless servers and stripped-down container images lack these graphical dependencies. When the dynamic linker attempts to load libxcb.so.1 and fails, Python raises an ImportError before executing any Cosmos-specific code.

Fixing libxcb.so.1 Import Failures in NVIDIA Cosmos

Installing Required Libraries on Ubuntu and Debian

The Cosmos repository documents the exact fix in its README.md troubleshooting section and within the audiovisual cookbooks. Install the three required packages using:

sudo apt-get update
sudo apt-get install -y libxcb1 libgl1 libglib2.0-0

• libxcb1 provides the XCB client library (libxcb.so.1) required by the X11 protocol.
• libgl1 supplies the OpenGL client library used by vision backends.
• libglib2.0-0 delivers the GLib runtime needed by the XCB stack.

Dockerfile Configuration for Containerized Deployments

If you are building a Docker image for Cosmos inference, add the installation step to your Dockerfile. The analysis references containers based on nvidia/cuda:13.0-runtime-ubuntu22.04 or similar CUDA-enabled bases:

FROM nvidia/cuda:13.0-runtime-ubuntu22.04

# Install system graphics dependencies required by Cosmos pipelines

RUN apt-get update && apt-get install -y \
    libxcb1 libgl1 libglib2.0-0 && \
    rm -rf /var/lib/apt/lists/*

# Continue with Python requirements installation...

Conda Environment Alternative

For Conda-managed environments without system-level access, you can install the libraries via conda-forge:

conda install -c conda-forge libxcb glib

Verifying the Installation

After installing the system libraries, verify the fix by attempting to import a Cosmos pipeline. The cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb and run_with_cosmos_framework.ipynb notebooks both expect this prerequisite:

from diffusers import Cosmos3OmniPipeline

# Or: from cosmos_framework.scripts import inference

print("Pipeline import succeeded")

If the import executes without raising ImportError: libxcb.so.1, the libraries are correctly linked and you can proceed with video generation.

Summary

• libxcb.so.1 errors indicate missing X11 system libraries on headless Linux servers, not Python package issues.
• Install three packages—libxcb1, libgl1, and libglib2.0-0—using apt-get on Debian/Ubuntu systems to satisfy graphics dependencies for torch and opencv.
• Container deployments require the same libraries added to Dockerfiles before importing Cosmos modules.
• Source documentation in README.md and the audiovisual cookbooks explicitly lists these requirements for both Diffusers and Cosmos-Framework pipelines.

Frequently Asked Questions

Why does NVIDIA Cosmos require X11 libraries on a server with no display?

NVIDIA Cosmos depends on computer vision libraries like opencv and torch that link against X11 client libraries for image buffer management and OpenGL context handling. Even without a physical display, these libraries require the XCB protocol implementation (libxcb.so.1) to initialize their graphics backends, causing the import failure on headless systems.

Can I solve this without sudo access to install system packages?

If you lack sudo privileges, use a Conda environment and install libxcb and glib from conda-forge using conda install -c conda-forge libxcb glib. Alternatively, request that your system administrator install the libxcb1, libgl1, and libglib2.0-0 packages, or use a Docker container where you control the base image.

Does this error affect both Diffusers and Cosmos-Framework pipelines?

Yes. According to the NVIDIA Cosmos source code, both the Diffusers integration shown in cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb and the native Cosmos-Framework path in run_with_cosmos_framework.ipynb import the same underlying vision dependencies that require libxcb.so.1. The fix applies identically to both approaches.

Where is this troubleshooting step documented in the repository?

The official fix appears in the Troubleshooting section of the main README.md at the repository root. Additionally, both audiovisual notebooks—run_with_diffusers.ipynb and run_with_cosmos_framework.ipynb—contain specific notes for headless servers with the exact apt-get install command required.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}