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

> Fix libxcb.so.1 import errors on headless servers. Install essential X11 libraries with apt-get to resolve Cosmos pipeline loading issues.

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

---

**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](https://github.com/NVIDIA/cosmos/blob/main/README.md) and the [audiovisual cookbooks](https://github.com/NVIDIA/cosmos/tree/main/cookbooks/cosmos3/generator/audiovisual) involves installing the missing system dependencies.

### Quick Fix on Ubuntu and Debian

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

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

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

```

### Conda Environment Alternative

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

```bash
conda install -c conda-forge libxcb glib

```


## Verifying the Installation

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

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