本文详解 python -m build 过程中因隔离环境尝试卸载/覆盖系统级（/usr/lib/python3/dist-packages）旧版 setuptools 而触发权限拒绝（Permission denied）的根本原因，并提供安全、可复现的非 root 解决方案，避免使用 sudo pip install 带来的系统污染风险。
本文详解 `python -m build` 过程中因隔离环境尝试卸载/覆盖系统级（`/usr/lib/python3/dist-packages`）旧版 setuptools 而触发权限拒绝（`Permission denied`）的根本原因，并提供安全、可复现的非 root 解决方案，避免使用 `sudo pip install` 带来的系统污染风险。
在使用 python -m build 构建 Python 包时，工具会自动创建一个临时的虚拟环境（isolated environment），并在其中安装构建所需依赖（如 setuptools>=61.0）。然而，当系统 Python（如 Ubuntu/Debian 的 /usr/bin/python3）预装了低版本 setuptools（如 59.6.0）于只读系统路径（/usr/lib/python3/dist-packages/）时，pip 在隔离环境中执行安装时可能错误地检测到该全局版本，并试图“回滚”或卸载它——尽管实际应仅操作隔离环境内的副本。由于该路径受 root 权限保护，pip 无法写入，最终抛出：
ERROR: Can't roll back setuptools; was not uninstalled ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/usr/local/lib/python3.10/dist-packages/distutils-precedence.pth'
值得注意的是：你本地用户安装的 setuptools 69.1.1（通过 pip list 可见）位于 ~/.local/lib/python3.10/site-packages/，但 build 工具默认不继承用户 site-packages，而是严格使用干净的隔离环境。问题不在于“本地版本未更新”，而在于 pip 在隔离环境中错误地扫描并关联了系统级只读安装，触发了不安全的卸载逻辑。
✅ 推荐解决方案（无需 sudo，安全可靠）：
立即学习“Python免费学习笔记（深入）”；
1. 强制使用用户级 pip 配置，禁用系统包干扰
在项目根目录下创建 pyproject.toml（若尚不存在），显式声明构建依赖及行为：
[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta" # 关键：禁止 pip 尝试修改/卸载系统包 [project] name = "your-package-name" version = "0.1.0"
2. 使用 --no-isolation（谨慎）或更优的 --config-settings 控制行为
实际更推荐的方式是升级构建工具链本身，确保其 pip 行为符合 PEP 517 规范：
# 确保 build 和 pip 均为最新稳定版（非系统包） pip install --upgrade --user build pip setuptools wheel # 构建时显式指定使用用户级 pip 并跳过危险的卸载步骤 python -m build --config-setting editable-verbose=true
3. 终极可靠方案：显式指定 Python 解释器路径（推荐）
避免调用系统 Python，改用 venv 创建的纯净环境执行构建：
# 1. 创建干净虚拟环境（不继承系统包） python -m venv .build-env source .build-env/bin/activate # Linux/macOS # .build-env\Scripts\activate # Windows # 2. 升级该环境内工具链 pip install --upgrade pip build setuptools wheel # 3. 执行构建（此时所有操作均在用户可写路径下） python -m build # 4. 构建完成后可安全删除 deactivate rm -rf .build-env
⚠️ 重要注意事项：
- ❌ 切勿执行 sudo pip install --upgrade setuptools：这会污染系统 Python，破坏包管理器（如 apt）对 Python 包的控制，引发不可逆依赖冲突。
- ✅ --user 安装仅影响当前用户，但 build 默认不使用它；因此需配合虚拟环境或配置文件显式引导。
- ? 可通过 python -m build --help 查看支持的 --config-setting 选项，部分新版 build 支持 installer=pip + --no-deps 等精细化控制。
- ? 若项目已使用 pyproject.toml，请确认 [build-system] 段落存在且 requires 明确包含高版本 setuptools，避免隐式 fallback 到系统旧版。
总结：该错误本质是构建工具在受限环境下对系统包路径的误判，而非用户环境配置错误。采用专用虚拟环境 + 显式工具链升级是最符合现代 Python 打包规范（PEP 517/518）的实践，兼顾安全性、可重现性与协作友好性。
