解决 Python paramiko 依赖 bcrypt 轮子构建失败问题-Python教程-PHP中文网

解决 Python paramiko 依赖 bcrypt 轮子构建失败问题

聖光之護

发布： 2025-08-21 11:14:23

原创

524人浏览过

解决 Python paramiko 依赖 bcrypt 轮子构建失败问题

本文旨在解决在安装 Python paramiko 或 pysftp 库时，由于 bcrypt 模块的轮子（wheel）构建失败导致的错误。核心问题源于 bcrypt 4.0.0 版本的兼容性问题。通过将 bcrypt 降级到 3.2.2 版本，可以有效解决此编译错误，确保 paramiko 及相关依赖的顺利安装。

问题描述：bcrypt 轮子构建失败

在使用 pip 安装 paramiko 或 pysftp 等依赖 bcrypt 库的 python 包时，用户可能会遇到 failed building wheel for bcrypt 的错误。此错误通常伴随着详细的 rust 编译失败信息，例如 error: cargo rustc ... failed with code 101。这表明 bcrypt 模块在尝试编译其 rust 后端时遇到了问题，导致无法成功构建其二进制轮子文件。

典型的错误输出片段如下所示：

    =============================DEBUG ASSISTANCE=============================
          If you are seeing a compilation error please try the following steps to
          successfully install bcrypt:
          1) Upgrade to the latest pip and try again. This will fix errors for most
             users. See: https://pip.pypa.io/en/stable/installing/#upgrading-pip
          2) Ensure you have a recent Rust toolchain installed. bcrypt requires
             rustc >= 1.64.0. (1.63 may be used by setting the BCRYPT_ALLOW_RUST_163
             environment variable)

          Python: 3.9.7
          platform: macOS-10.16-x86_64-i386-64bit
          pip: n/a
          setuptools: 69.0.2
          setuptools_rust: 1.8.1
          rustc: 1.74.0 (79e9716c9 2023-11-13)
          =============================DEBUG ASSISTANCE=============================

      error: `cargo rustc --lib --message-format=json-render-diagnostics --manifest-path src/_bcrypt/Cargo.toml --release -v --features pyo3/extension-module --crate-type cdylib -- -C 'link-args=-undefined dynamic_lookup -Wl,-install_name,@rpath/_bcrypt.abi3.so'` failed with code 101
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for bcrypt
Failed to build bcrypt
ERROR: Could not build wheels for bcrypt, which is required to install pyproject.toml-based projects

登录后复制

尽管错误信息中建议升级 pip 或检查 Rust 工具链，但对于此特定问题，根源通常在于 bcrypt 4.0.0 版本引入的兼容性或编译问题，而非用户环境配置不当。

解决方案：降级 bcrypt 版本

解决此问题的最直接且有效的方法是将 bcrypt 库降级到 4.0.0 之前的稳定版本。经验证，bcrypt 3.2.2 版本能够有效避免此编译错误。

操作步骤：

立即学习“Python免费学习笔记（深入）”；

卸载当前可能已安装的 bcrypt 版本（可选但推荐）： 为确保干净的安装，如果之前尝试安装过 bcrypt 并失败，可以先尝试卸载它。
```
pip uninstall bcrypt
# 或者
pip3 uninstall bcrypt
```
登录后复制
如果提示 WARNING: Skipping bcrypt as it is not installed. 则表示未安装，无需理会。

AI建筑知识问答
用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情
安装指定版本的 bcrypt： 使用 pip install 命令并指定 bcrypt 的版本为 3.2.2。使用 ~= 运算符表示安装兼容 3.2.2 的最新版本，但在本例中，由于 3.2.2 是 4.0.0 之前最新的稳定版本，它将直接安装 3.2.2。
```
pip install bcrypt~=3.2.2
# 如果您使用Python 3，请使用pip3：
pip3 install bcrypt~=3.2.2
```
登录后复制
成功执行此命令后，bcrypt 3.2.2 版本将被正确安装。
重新安装 paramiko 或其他依赖库： 在 bcrypt 降级并成功安装后，您可以再次尝试安装 paramiko 或之前导致错误的库。
```
pip install paramiko
# 或者
pip3 install paramiko
```
登录后复制
此时，paramiko 应该能够顺利安装，因为它将使用已安装的 bcrypt 3.2.2 版本。

原理分析

bcrypt 是一个密码哈希库，其核心功能部分由 Rust 实现，并通过 pyo3 框架与 Python 进行绑定。当 bcrypt 发布 4.0.0 版本时，可能引入了某些与特定操作系统、Python 版本或 Rust 工具链版本不兼容的改动，导致在编译阶段出现问题。通过将 bcrypt 降级到 3.2.2 版本，我们实际上是回退到了一个已知稳定且在更广泛环境中兼容的版本，从而绕过了 4.0.0 版本中存在的编译问题。

注意事项

虚拟环境的重要性： 强烈建议在进行任何 Python 包安装和版本管理时使用虚拟环境（如 venv 或 conda）。这可以隔离项目依赖，避免不同项目之间的包冲突，并防止对系统全局 Python 环境造成不必要的修改。
Rust 工具链： 尽管本解决方案主要针对 bcrypt 版本问题，但如果降级操作未能解决问题，您仍应按照错误提示检查您的 Rust 工具链是否已安装且版本符合 bcrypt 的要求（例如 rustc >= 1.64.0）。可以通过运行 rustc --version 来检查。
未来版本更新： 随着 bcrypt 库及其依赖的持续开发，未来版本可能会修复 4.0.0 中存在的问题。因此，在未来安装时，您可以尝试安装最新版本。如果再次遇到类似问题，再考虑版本回溯。
兼容性： 在降级任何库时，请注意其与您项目中其他依赖的兼容性。bcrypt 3.2.2 与 paramiko 是兼容的，但对于其他复杂项目，可能需要进行额外的测试。

总结

当在安装 paramiko 或 pysftp 时遇到 bcrypt 轮子构建失败的错误，特别是与 Rust 编译相关的错误时，最有效的解决方案是将 bcrypt 库降级到 3.2.2 版本。这个方法能够绕过 bcrypt 4.0.0 版本可能存在的兼容性问题，从而确保依赖库的顺利安装。在进行此类操作时，使用虚拟环境是最佳实践，以维护项目依赖的整洁性。

以上就是解决 Python paramiko 依赖 bcrypt 轮子构建失败问题的详细内容，更多请关注php中文网其它相关文章！