项目构建时无法安装正确版本的setuptools包

问题背景 #

执行python -m build构建Python包时触发权限错误，核心报错片段：

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，但构建过程却调用了/usr/lib/python3/dist-packages下的系统级旧版本59.6.0。

核心原因 #

python -m build默认会创建隔离虚拟环境执行构建流程，这个隔离环境会自动继承系统Python的基础包（即/usr/lib/python3/dist-packages目录下的内容），但用户目录~/.local/lib/python3.10/site-packages中的用户级安装包不会被纳入隔离环境。当构建要求安装>=61.0版本的setuptools时，隔离环境尝试安装新版本，却因无root权限无法卸载/覆盖系统目录下的旧版本setuptools，最终触发权限错误。

解决办法 #

方法1：跳过隔离环境构建（快速临时方案） #

直接复用当前已升级好依赖的用户环境进行构建，无需创建隔离环境：

python -m build --no-isolation

前提：当前环境的setuptools（已升级到69.1.1）和wheel版本满足构建要求。

方法2：使用独立虚拟环境构建（推荐方案） #

创建完全独立的用户级虚拟环境，彻底隔离系统依赖：

# 创建专属构建虚拟环境
python -m venv ~/my-build-env
# 激活虚拟环境
source ~/my-build-env/bin/activate
# 升级环境内的构建工具
pip install --upgrade pip setuptools build
# 执行包构建
python -m build
# 构建完成后退出虚拟环境
deactivate

这种方式完全避免系统依赖干扰，且不需要root权限，是最安全的构建方式。

方法3：升级系统级setuptools（需谨慎操作） #

若必须使用系统Python环境，可通过root权限升级系统级setuptools至符合要求的版本：

sudo pip install --upgrade setuptools

注意：修改系统Python的包可能导致系统自带工具依赖异常，操作前需确认风险。

内容的提问来源于stack exchange，提问作者Aram Papazian