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

> Troubleshoot Cosmos 3 import errors by installing missing libxcb.so.1 libraries. Resolve Shared Object File issues quickly and get your pipeline running.

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

---

**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:

```python
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`](https://github.com/NVIDIA/cosmos/blob/main/README.md), the [`cookbooks/cosmos3/README.md`](https://github.com/NVIDIA/cosmos/blob/main/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:

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

```

This exact command appears in the [`README.md`](https://github.com/NVIDIA/cosmos/blob/main/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:

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

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

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