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

> Troubleshoot libxcb.so.1 import errors on headless servers. Install essential X11 libraries with apt-get to fix NVIDIA Cosmos pipeline issues in Linux or Docker.

- Repository: [NVIDIA Corporation/cosmos](https://github.com/NVIDIA/cosmos)
- Tags: how-to-guide
- Published: 2026-06-06

---

**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`](https://github.com/NVIDIA/cosmos/blob/main/README.md) troubleshooting section and within the audiovisual cookbooks. Install the three required packages using:

```bash
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:

```dockerfile
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:

```bash
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:

```python
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`](https://github.com/NVIDIA/cosmos/blob/main/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`](https://github.com/NVIDIA/cosmos/blob/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.