问题描述
在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免费学习笔记（深入）”；
-
尝试安装目标库并观察错误： 首先，尝试直接安装您需要的库，例如 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 版本可能存在的编译问题，从而确保主要库的顺利安装和项目运行。
