Cosmos 3 Troubleshooting: Fix libxcb.so.1 Cannot Open Shared Object File

Install the missing X11 client system libraries—libxcb1, libgl1, and libglib2.0-0—on your Debian/Ubuntu host or container, then re-import the Cosmos 3 pipeline to resolve the ImportError.

Running NVIDIA Cosmos 3 inference pipelines on a headless server or minimal Docker container often leads to a dynamic linker failure for X11 graphics libraries. When deep-learning frameworks like Diffusers or VLLM load PyTorch extensions compiled against the X11 stack, the missing libxcb.so.1 shared object triggers an immediate ImportError. This Cosmos 3 troubleshooting guide walks you through the root cause and the exact fix documented in the official NVIDIA cosmos repository.

Why Cosmos 3 Requires X11 Libraries on Headless Systems

Cosmos 3 relies on deep-learning pipelines built on top of PyTorch and other GPU-accelerated libraries. Some of these underlying C++ extensions are compiled against the X11 graphics stack, specifically libxcb, libGL, and libglib.

On a headless server or a stripped-down container image, these X-libraries are typically absent. When the Python process imports a pipeline that links against them—such as the audiovisual generators in the cookbooks/cosmos3/generator/audiovisual/ directory—the dynamic loader fails with:

ImportError: libxcb.so.1: cannot open shared object file

This is purely an OS-level dependency gap. It is unrelated to the Python source code in the Cosmos framework itself, as noted in the repository's README.md, the cookbooks/cosmos3/README.md overview, and the notebook examples run_with_diffusers.ipynb and run_with_cosmos_framework.ipynb.

Resolving libxcb.so.1 Cannot Open Shared Object File in Cosmos 3

The NVIDIA cosmos documentation provides a straightforward resolution: install the missing system packages and verify the import.

Install Missing System Packages on Debian or Ubuntu

The fastest fix is to update your package list and install the three libraries that satisfy the X11 dependencies:

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

This exact command appears in the README.md under the troubleshooting section, as well as in cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb and cookbooks/cosmos3/generator/audiovisual/run_with_cosmos_framework.ipynb. Run it directly on the host or inside your running container.

Verify the Fix by Re-importing the Pipeline

After installation, confirm the dynamic linker can resolve all symbols by importing a Diffusers pipeline:

import torch
from diffusers import StableDiffusionPipeline

pipe = StableDiffusionPipeline.from_pretrained(
    "runwayml/stable-diffusion-v1-5",
    torch_dtype=torch.float16
)
pipe = pipe.to("cuda")
print("Pipeline loaded successfully")

If the script executes without raising ImportError: libxcb.so.1: cannot open shared object file, the Cosmos 3 environment is correctly configured.

Optional: Use a Pure-CPU Software Fallback

If your environment restricts system package installation, you can force Qt and OpenGL to use a software rasterizer. Set the following environment variable before launching your Python process:

export LIBGL_ALWAYS_SOFTWARE=1

This avoids the libxcb dependency entirely, though it may reduce rendering performance. It is useful for highly restricted or locked-down headless nodes where sudo apt-get is unavailable.

Fix Headless Containers with a Dockerfile Update

For container-based Cosmos 3 workflows, add the library installation to your image build. The following Dockerfile snippet installs the required X11 libraries on an NVIDIA CUDA base image:

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

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

Rebuild the image and run your Cosmos 3 notebooks—such as cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb—inside the updated container. The libxcb.so.1 error will no longer occur at import time.

Summary

• Root cause: PyTorch-based pipelines in Cosmos 3 link against X11 client libraries that are missing on headless servers and minimal containers.
• Primary fix: Run sudo apt-get install -y libxcb1 libgl1 libglib2.0-0 on Debian/Ubuntu systems or add the packages to your Dockerfile.
• Verification: Re-import a Diffusers StableDiffusionPipeline to confirm the linker resolves libxcb.so.1.
• Fallback: Set LIBGL_ALWAYS_SOFTWARE=1 to bypass hardware GL dependencies in restricted environments.
• Documentation: The NVIDIA cosmos repository documents this in README.md and the audiovisual generator notebooks under cookbooks/cosmos3/generator/audiovisual/.

Frequently Asked Questions

Can I run Cosmos 3 without installing X11 libraries?

Yes, but only if you use a software rendering fallback. Setting LIBGL_ALWAYS_SOFTWARE=1 before starting your Python process allows Qt and OpenGL to use a CPU rasterizer, bypassing the need for libxcb1 system packages. You may see slower performance, so installing the libraries is still the preferred fix.

Does this error mean the Cosmos 3 framework is broken?

No. The libxcb.so.1 error is an OS-level dependency issue, not a bug in the Cosmos 3 Python source code. The dynamic linker simply cannot find the shared object required by the underlying GPU-accelerated C++ extensions used by Diffusers and VLLM.

Which Cosmos 3 files document this troubleshooting step?

The fix is officially documented in the repository's README.md and repeated in the notebook examples cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb and cookbooks/cosmos3/generator/audiovisual/run_with_cosmos_framework.ipynb. Both sources include the same apt-get install command for headless environments.

Is this error specific to certain Cosmos 3 notebooks?

It typically surfaces when running the audiovisual generator cookbooks or any pipeline that pulls in PyTorch extensions compiled against the X11 stack. Any headless environment executing those notebooks without libxcb1 installed will encounter the same shared-object error.

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