使用pip安装自定义whl包时触发Invalid requirement错误求助

问题分析 #

你遇到的错误根源是2.0.0_SNAPSHOT版本号不符合PEP 440规范，新版本pip会严格校验包元数据中的版本格式。虽然之前setuptools 65.5.1能生成该格式的whl，但pip版本升级或依赖工具变更后，校验逻辑收紧，导致安装失败。

排查步骤 #

1. 检查pip版本变更
   执行pip --version，对比昨日使用的版本。pip有时会自动更新（比如系统包管理或自动升级脚本触发），新版本对PEP 440的校验标准更严格。

2. 确认依赖工具版本
   执行pip list | grep -E "setuptools|wheel"，确认setuptools是否仍为65.5.1，以及wheel包是否有夜间自动更新。即便固定了setuptools版本，wheel包升级也可能影响whl元数据的生成或pip的解析逻辑。

3. 验证whl的元数据
   解压查看whl内的版本信息：

   unzip -p target/custom_utils-2.0.0_SNAPSHOT-py3-none-any.whl custom_utils-2.0.0_SNAPSHOT.dist-info/METADATA
   

   确认Version字段为2.0.0_SNAPSHOT，该格式确实违反PEP 440（规范要求预发布版本使用.dev、.a、.b、.rc等后缀）。

解决方案 #

方案1：回退pip到兼容版本（应急使用）

如果确认是pip版本升级导致的问题，回退到昨日正常工作的版本，例如：

pip install pip==22.3.1

之后再执行原安装命令即可。

方案2：修改版本号符合PEP 440规范（长期推荐）

调整项目的版本定义（setup.py或pyproject.toml），将2.0.0_SNAPSHOT替换为符合规范的格式，比如：

• 快照版本用2.0.0.dev0（或带日期的2.0.0.dev20240520）
• 测试版本用2.0.0a1（Alpha）或2.0.0b1（Beta）

修改后重新生成whl：

python setup.py bdist_wheel

再执行安装命令即可。

方案3：固定wheel包版本

如果是wheel包升级导致的问题，回退到之前兼容的版本，例如：

pip install wheel==0.38.4

重新生成whl后再执行安装。

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