Linux安装Python时提示ssl模块缺失或编译报错怎么办

清欢

发布时间：2026-11-07 | 9人浏览过

原创

解决在Linux系统源码编译安装Python时提示No module named _ssl或OpenSSL版本不兼容的报错，涵盖依赖补齐、编译配置与结果验证。

在 Linux 环境下源码编译安装 Python 时，如果终端抛出 No module named '_ssl'、pip is configured with locations that require TLS/SSL 或 configure 阶段提示 SSL module cannot be built，核心原因几乎只有两个：编译所需的 OpenSSL 头文件未安装，或者当前系统的 OpenSSL 版本过旧，未达到目标 Python 版本的最低兼容要求。解决路径是先补齐开发包，若系统库版本不达标则独立编译高版本 OpenSSL，最后带路径重新执行 Python 的配置与编译。

一、问题现象与直接成因

从源码构建 Python 时，默认情况下构建脚本会检测系统中可用的第三方开发依赖。如果缺少对应的头文件与静态库，构建系统并不会中断退出，而是会跳过对应扩展模块的构建，仅仅在编译末尾的模块汇总信息里输出警告：

Python build finished successfully!
The necessary bits to build these optional modules were not found:
_ssl                  _hashlib
To find the necessary bits, look in setup.py in detect_modules() for the module's name.

用户如果在此时继续执行 make install，Python 解释器依然能够正常生成并运行基本命令，但任何涉及网络请求的操作都会失败。最常见的报错发生在使用 pip install 安装第三方包时：

WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.
Could not fetch URL https://pypi.org/simple/...: There was a problem confirming the ssl certificate: Can't connect to HTTPS URL because the SSL module is not available. - skipping

在交互式环境中手动执行 import ssl，则会直观地抛出 ModuleNotFoundError: No module named '_ssl'。

图 1：编译期因缺少开发头文件导致 _ssl 模块被跳过的传导机制

二、常见说法辨析：终端有 openssl 命令，为什么还会报错？

许多初学者在遇到此错误时，会下意识在终端输入 openssl version，看到系统返回了类似 OpenSSL 1.1.1 的版本号，便得出“系统已经有 SSL，是 Python 源码有问题”的结论。这种判断混淆了运行时可执行工具与C语言编译开发包。

在绝大多数 Linux 发行版中，包管理器把软件包拆分为了运行库与开发头文件：

运行时程序（如 openssl）：仅提供命令行交互与已编译好的动态链接库，供日常用户和已编译好的软件调用，不包含 C 语言的头文件（.h 文件）。
开发库（如 libssl-dev 或 openssl-devel）：专门提供给编译器使用的 C 头文件、链接元数据（pkg-config 配置文件）及静态库。

Python 在执行 ./configure 和 make 时，需要利用头文件检查数据结构，并生成桥接 C 扩展。没有安装对应的开发包，编译器就无法解析 SSL 相关的符号，自然无法构建出 _ssl.so 模块。

三、常规排查：通过系统包管理器补齐依赖

在较新的 Linux 系统（如 Ubuntu 20.04+、Debian 11+、Rocky Linux 8+、CentOS 8+）上编译安装主流 Python 版本时，只需要通过系统的原生包管理器补齐开发包，即可满足构建条件。

1. Ubuntu 与 Debian 系系统

在终端中以管理员权限执行包索引更新并安装编译套件与 SSL 开发包：

sudo apt-get update
sudo apt-get install -y build-essential zlib1g-dev libssl-dev libffi-dev

2. RHEL、CentOS 与 Rocky Linux 系系统

在 Red Hat 系列系统上，对应包名为 openssl-devel：

# CentOS 7 / RHEL 7
sudo yum install -y gcc zlib-devel openssl-devel libffi-devel

# CentOS 8 / Rocky Linux / AlmaLinux
sudo dnf install -y gcc zlib-devel openssl-devel libffi-devel

依赖安装完成后，必须返回 Python 源码目录彻底清理旧的编译中间产物，随后重新执行配置、编译与安装：

cd /path/to/Python-3.x.x
make clean
./configure --prefix=/usr/local/python3 --enable-optimizations
make -j$(nproc)
sudo make altinstall

生产环境提示：推荐使用 sudo make altinstall 而不是 make install。altinstall 不会覆盖系统默认的 /usr/bin/python3 软链接，能防止依赖系统 Python 的系统级脚本（如 apt、yum、dnf）出现异常。

四、深层问题：系统 OpenSSL 版本过旧导致编译报错

如果补齐了开发包后，在执行 ./configure 时直接报错停止，或者 make 时出现大量与 OpenSSL 相关的语法错误，通常意味着系统的 OpenSSL 物理版本已经过旧，不被目标 Python 版本支持。

自 Python 3.10 起，Python 官方正式废弃了对旧版 OpenSSL 1.0.2 及更早版本的支持，要求构建环境必须配备 OpenSSL 1.1.1 或更高版本。在一些长期维护的旧系统（如 CentOS 7 默认仅提供 OpenSSL 1.0.2k）上，即使执行 yum install openssl-devel，版本依然停留在 1.0.2，此时构建 Python 3.10 及以上版本必然报错：

Could not build the ssl module!
Python requires an OpenSSL 1.1.1 or newer

图 2：Python 编译工具链对底层加密库的最低版本基准

五、实操方案：独立源码编译 OpenSSL 并链接至 Python

当系统默认仓库无法升级 OpenSSL，或者为了不破坏旧系统核心服务（避免系统整体 glibc 或核心运行库崩溃）时，最稳妥的策略是将新版 OpenSSL 安装到独立目录（如 /usr/local/openssl），在构建 Python 时单独引用该目录。

图 3：跨系统版本自定义安装 OpenSSL 并桥接 Python 的操作步骤

步骤一：编译安装独立版本的 OpenSSL

下载 OpenSSL 1.1.1 稳定分支源码（以 1.1.1w 为例），解压并指定安装路径：

# 进入临时构建目录并下载
cd /usr/local/src
wget https://www.openssl.org/source/openssl-1.1.1w.tar.gz
tar -zxvf openssl-1.1.1w.tar.gz
cd openssl-1.1.1w

# 配置：--prefix 指定安装目录，shared 生成动态链接库，zlib 启用压缩
./config --prefix=/usr/local/openssl --openssldir=/usr/local/openssl/ssl shared zlib

# 编译并安装
make -j$(nproc)
sudo make install

步骤二：登记动态链接库缓存

为了让系统在运行时顺利找到新建目录中的 libssl.so 和 libcrypto.so，需要将库路径注入动态链接器：

# 将库路径加入动态链接目录
echo "/usr/local/openssl/lib" | sudo tee /etc/ld.so.conf.d/openssl-1.1.1.conf

# 刷新动态链接缓存
sudo ldconfig -v | grep ssl

步骤三：重新配置并编译 Python

回到 Python 源码根目录。必须显式传入 --with-openssl 参数，并通过 --with-openssl-rpath 将链接路径硬编码到编译出来的 Python 二进制文件中，避免后期切换环境导致动态库搜寻失败：

cd /path/to/Python-3.x.x

# 彻底清理历史编译残余
make distclean

# 配置 Python 源码
./configure \
    --prefix=/usr/local/python3 \
    --with-openssl=/usr/local/openssl \
    --with-openssl-rpath=/usr/local/openssl/lib \
    --enable-optimizations

# 编译与安装
make -j$(nproc)
sudo make altinstall

六、验证与结果确认

安装完成后，不能只看退出码是否为 0，必须执行两个维度的验证，以确定模块是否真正编译成功。

1. 交互式命令行模块验证

直接通过新安装的 Python 解释器调用 ssl 模块，并打印其底层所链接的 OpenSSL 版本信息：

/usr/local/python3/bin/python3 -c "import ssl; print('SSL OK:', ssl.OPENSSL_VERSION)"

正常输出示例：

SSL OK: OpenSSL 1.1.1w  11 Sep 2023

若能够顺利输出类似上述版本信息且无任何报错，证明 Python 的 _ssl C 扩展模块已经正确链接并可用。

2. pip 网络与 TLS 链路验证

测试依赖网络加密链路的实际命令，使用新生成的 pip 尝试查询或者安装纯净包：

/usr/local/python3/bin/pip3 --version
/usr/local/python3/bin/pip3 install --upgrade pip --dry-run

如果命令执行过程中不再弹出任何 pip is configured with locations that require TLS/SSL 警告，并且能够正常返回索引检索信息，说明整套环境的网络与加密模块已经修复完毕。

图 4：解决 Linux 下 Python 缺失 SSL 模块的整体诊断与处理路线

七、总结与排错备忘

遇到 SSL 缺失问题时，按照以下逻辑执行处理最为高效：

定位版本关系：先查看目标 Python 版本。如果是 Python 3.10 及以上版本，必须确保 OpenSSL 版本不低于 1.1.1。
首选官方包管理：在较新的主流发行版中，直接安装 libssl-dev（Debian/Ubuntu）或 openssl-devel（RHEL/CentOS）是最快且最安全的方案。
旧系统采用独立隔离编译：旧系统切忌强行覆盖系统的 /usr/lib64/libssl.so，而应将新版 OpenSSL 安装到 /usr/local/openssl，并在 Python ./configure 阶段通过 --with-openssl 与 --with-openssl-rpath 进行定向绑定。
切记重新编译前清理缓存：修改完系统环境或参数后，务必进入 Python 源码目录执行 make clean 或 make distclean，防止旧的缓存对象导致配置变更无法生效。