Linux libGL.so.1 缺失：apt install libgl1 一行解决

症状

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

出现在代码里 import OpenCV（cv2）时——CodeFormer 内部用 OpenCV 做图像处理。

原因

OpenCV 的 cv2 依赖系统的 libGL（OpenGL 库）。在有图形界面的系统（Windows、带桌面的 Ubuntu）上这个库默认就有。但在无界面的服务器环境里：

• Docker 容器（尤其是 slim 镜像）
• AutoDL / 矩池云的纯命令行实例
• 远程 SSH 登录的裸 Ubuntu / Debian 服务器

默认没装 libGL——因为无界面环境不需要 OpenGL。

一行解决

# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y libgl1

装完后 python -c "import cv2; print(cv2.__version__)" 应该不报错误。

其他发行版

# CentOS / RHEL
sudo yum install -y mesa-libGL

# Fedora
sudo dnf install -y mesa-libGL

# Arch Linux
sudo pacman -S mesa

Docker 容器里

如果在 Docker 里跑，Dockerfile 里加一行：

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

# 装 libGL
RUN apt-get update && apt-get install -y libgl1

# ... 后续 CodeFormer 环境搭建

为什么会遇到

CodeFormer 依赖链上有 OpenCV → OpenCV 需要 libGL。这条依赖在开发机（有图形界面）上隐式存在，但在服务器上要显式装。

类似的问题还有：

• ImportError: libgthread-2.0.so.0 → apt-get install -y libglib2.0-0
• ImportError: libsm.so.6 → apt-get install -y libsm6 libxext6 libxrender-dev

可以一次性把这些都装上：

sudo apt-get update && sudo apt-get install -y \
    libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev

快速验证

python -c "
import cv2
import torch
print(f'OpenCV: {cv2.__version__}')
print(f'PyTorch: {torch.__version__}')
print(f'CUDA: {torch.cuda.is_available()}')
print('环境 OK')
"

如果这条脚本正常输出三个版本号 → 环境搭好了。