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

解决 Python paramiko 安装中 bcrypt 依赖构建失败问题

聖光之護

发布： 2025-08-21 12:08:17

原创

760人浏览过

解决 Python paramiko 安装中 bcrypt 依赖构建失败问题

本文旨在解决在安装 paramiko 或 pysftp 等Python库时，因其依赖项 bcrypt 版本问题导致的“Failed building wheel for bcrypt”错误。核心解决方案是针对 bcrypt 库的特定版本兼容性问题，通过将其降级到已知稳定且兼容的版本（例如 3.2.2）来绕过编译失败，从而确保主库的顺利安装。

问题描述

在python开发中，当尝试使用 pip install paramiko 或 pip install pysftp 命令安装sftp/ssh相关的库时，用户可能会遇到一个常见的错误：“failed building wheel for bcrypt”。这个错误通常伴随着详细的编译输出，指示 cargo rustc 命令执行失败，错误代码为 101。尽管错误信息中会提示升级pip、安装rust工具链（要求 rustc >= 1.64.0）等调试建议，但即使按照这些建议操作，问题依然可能存在。这表明问题并非简单地缺少编译环境，而是 bcrypt 库自身在特定版本（尤其是 4.0.0 及以上版本）与某些环境或其依赖的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

登录后复制

根本原因分析

此问题的根本原因在于 bcrypt 库的版本兼容性。从 bcrypt 4.0.0 版本开始，其内部实现可能引入了某些变化，这些变化在特定的操作系统（例如macOS）、Python版本或Rust工具链组合下，会导致编译失败。由于 paramiko 和 pysftp 都将 bcrypt 作为间接或直接的依赖项，因此当 pip 尝试安装这些库时，会连带尝试安装最新版本的 bcrypt，从而触发上述构建错误。

解决方案：降级 bcrypt 版本

最直接且有效的解决方案是将 bcrypt 库降级到 4.0.0 之前的稳定版本。经过实践验证，bcrypt 3.2.2 版本在大多数环境中表现出良好的兼容性，能够避免构建错误。

操作步骤：

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

AI建筑知识问答

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

查看详情

尝试安装目标库并观察错误： 首先，尝试直接安装您需要的库，例如 paramiko：
```
pip install paramiko
```
登录后复制
如果出现“Failed building wheel for bcrypt”错误，则继续下一步。
预先安装或降级 bcrypt： 在安装 paramiko 或 pysftp 之前，手动安装指定版本的 bcrypt。推荐使用 ~= 操作符，它表示安装与指定版本兼容的最新版本（例如 ~=3.2.2 会安装 3.2.x 系列中最新的版本，但不会升级到 4.0.0 或更高版本）。
```
pip install bcrypt~=3.2.2
# 或者如果您使用的是Python 3，通常也是一样的命令
pip3 install bcrypt~=3.2.2
```
登录后复制
执行此命令后，bcrypt 3.2.2 版本（或其兼容的最新版本）将被成功安装。
重新安装目标库： 在 bcrypt 成功安装后，再次尝试安装 paramiko 或 pysftp。此时，pip 会发现 bcrypt 依赖已经满足，从而跳过其构建过程，直接安装 paramiko 的其余部分。
```
pip install paramiko
# 或者
pip install pysftp
```
登录后复制
这次安装应该能够顺利完成。

注意事项

虚拟环境（Virtual Environments）： 强烈建议在进行任何Python项目开发时使用虚拟环境（如 venv 或 conda）。这可以隔离项目依赖，避免不同项目之间的库版本冲突，并使问题诊断和解决更加便捷。在虚拟环境中执行上述命令，可以确保更改仅限于当前项目。
版本兼容性： 虽然 bcrypt~=3.2.2 解决了当前问题，但在未来的Python版本、操作系统更新或 paramiko / pysftp 更新中，bcrypt 的兼容性问题可能会有所变化。如果未来再次遇到类似问题，可以尝试查找 bcrypt 的其他稳定版本或查阅相关库的官方文档，了解其推荐的 bcrypt 版本。
Rust 工具链： 尽管本解决方案通过降级 bcrypt 绕过了Rust编译问题，但对于其他需要Rust编译的Python库，确保您的系统上安装了最新且兼容的Rust工具链（通过 rustup 管理）仍然是一个良好的实践。

总结

当遇到 pip install paramiko 或 pip install pysftp 过程中 bcrypt 依赖构建失败的错误时，最有效的解决方案是手动将 bcrypt 库降级到 3.2.2 等已知稳定的兼容版本。通过 pip install bcrypt~=3.2.2 预先安装 bcrypt，可以规避其 4.0.0 版本可能存在的编译问题，从而确保主要库的顺利安装和项目运行。

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