How to Resolve libxcb.so.1 Import Failures on Headless Servers for NVIDIA Cosmos

Install the missing X11 system libraries libxcb1, libgl1, and libglib2.0-0 using apt-get to fix the ImportError when loading Cosmos pipelines on headless Linux servers.

When deploying the NVIDIA Cosmos video generation models on headless Linux servers or minimal Docker containers, importing the Python pipelines often triggers an ImportError: libxcb.so.1: cannot open shared object file. This occurs because the underlying graphics dependencies required by PyTorch and OpenCV are absent in stripped-down environments. Fortunately, resolving these libxcb.so.1 import failures on headless servers requires only installing three standard system packages.

Why the Import Error Occurs on Headless Systems

The Cosmos pipelines—including the Diffusers and Cosmos-Framework variants—depend on Python libraries like torch and opencv that dynamically link against X11 windowing libraries. On a desktop workstation, libxcb, libGL, and libglib are present as part of the graphical environment. However, cloud VMs and lightweight containers lack these libraries, causing the dynamic linker to fail before any Python code executes when it cannot locate libxcb.so.1.

Installing the Required X11 Libraries

The fix documented in the Cosmos repository README.md and the audiovisual cookbooks involves installing the missing system dependencies.

Quick Fix on Ubuntu and Debian

For most cloud-based headless servers running Ubuntu or Debian, execute:

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

This command installs:

• libxcb1: Provides the XCB client library (libxcb.so.1)
• libgl1: Supplies the OpenGL client library required by vision backends
• libglib2.0-0: Delivers the GLib runtime needed by the XCB stack

Docker Container Configuration

If you are containerizing your Cosmos deployment, add the installation step to your Dockerfile. For example, when using an NVIDIA CUDA base image:

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 Cosmos installation...

Conda Environment Alternative

If you prefer managing dependencies through Conda rather than system packages, install the libraries via conda-forge:

conda install -c conda-forge libxcb glib

Verifying the Installation

After installing the system libraries, verify that the Cosmos pipelines import without error:

from diffusers import Cosmos3OmniPipeline

# Or for the Framework pipeline:

# from cosmos_framework.scripts import inference

print("Pipeline import succeeded")

If the command executes without raising ImportError: libxcb.so.1, the environment is correctly configured.

Source Documentation References

The official troubleshooting guidance appears in several locations within the NVIDIA/cosmos repository:

• README.md (Troubleshooting section): Contains the canonical note on "Import fails with libxcb.so.1: cannot open shared object file" alongside the exact apt-get command.
• cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb: Provides the same headless server guidance specifically for users running the Diffusers pipeline.
• cookbooks/cosmos3/generator/audiovisual/run_with_cosmos_framework.ipynb: Replicates the fix for the Cosmos-Framework pipeline, ensuring both variants document the dependency requirements.

Summary

• libxcb.so.1 import failures on headless servers stem from missing X11 libraries required by PyTorch and OpenCV bindings.
• Installing libxcb1, libgl1, and libglib2.0-0 via apt-get resolves the dynamic linker error on Ubuntu/Debian systems.
• For Docker deployments, include these packages in the image build to avoid runtime failures.
• The NVIDIA Cosmos repository documents this fix in README.md and the audiovisual cookbook notebooks.

Frequently Asked Questions

Why does NVIDIA Cosmos require X11 libraries on a headless server?

While the Cosmos pipelines do not open graphical windows during inference, they depend on OpenCV and PyTorch modules that link against X11 client libraries for image processing capabilities. These dynamic dependencies exist regardless of whether a display is available, requiring the libxcb shared objects to be present on the system.

Can I resolve the libxcb.so.1 error without sudo access?

If you cannot install system packages, use a Conda environment to install libxcb and glib from conda-forge. This places the shared libraries in your user's Conda path, which the dynamic linker can access without requiring root privileges or system-wide installation.

Which specific Cosmos pipelines are affected by this issue?

Both the Diffusers pipeline (Cosmos3OmniPipeline) and the Cosmos-Framework pipeline trigger this error during import, as documented in run_with_diffusers.ipynb and run_with_cosmos_framework.ipynb. Any Cosmos variant relying on OpenCV for video processing will encounter this issue on minimal Linux installations.

Do I need to install these libraries for every new Docker container?

Yes. Since containers are ephemeral and isolated from the host system, you must include libxcb1, libgl1, and libglib2.0-0 in the Dockerfile for each Cosmos deployment. Adding these to your base image ensures consistent pipeline initialization across all container instances.

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