修改maturin项目名称后，Linux容器中pip无法安装分支包问题排查

一、获取更详细的pip安装错误信息 #

• 强制重新安装并禁用缓存，输出完整安装日志：

  pip install my-project-branch-name --verbose --no-cache-dir
  

• 启用pip调试模式生成底层日志：

  PIP_DEBUG=1 pip install my-project-branch-name
  

  执行后当前目录会生成pip-debug.log，包含包下载、解压、元数据验证等全流程细节。
• 手动检查wheel包结构：
  下载对应Linux版本的wheel包后，执行以下命令确认内部目录和元数据是否合规：

  unzip -l my_project_branch_name-*.whl
  

  需确保输出中包含my_project/模块目录，以及与包名匹配的my_project_branch_name-*.dist-info/元数据目录。

二、无需修改Python模块名的包名配置修改 #

要保留import my_project的导入方式，仅需修改包发布名称，无需改动模块本身，调整以下配置：

1. pyproject.toml
   修改[project]下的包名字段，同时保留原模块的路径配置：

   [project]
   name = "my-project-branch-name"  # 分支专属发布包名
   version = "x.y.z-branch-suffix"  # 可选：添加分支版本后缀区分正式包
   packages = ["my_project"]        # 保持指向原Python模块目录
   

2. pyproject.toml中的maturin配置
   明确指定模块名，避免maturin自动推断出错：

   [tool.maturin]
   name = "my-project-branch-name"  # 与project.name保持一致
   module-name = "my_project"       # 保留原Python模块名
   

3. Cargo.toml与src/lib.rs
   • Cargo.toml中的name字段无需修改，Rust crate名称不影响Python包的发布与导入。
   • src/lib.rs中的#[pymodule]宏保持原模块名：

     #[pymodule]
     fn my_project(_py: Python, m: &PyModule) -> PyResult<()> {
         // 原有模块代码
     }
     

三、Linux容器安装失败的常见排查点 #

1. 升级容器内的pip版本
   旧版pip可能对新格式wheel兼容性不足，先升级pip：

   pip install --upgrade pip
   

2. 确保wheel包的系统兼容性
   构建Linux wheel时，使用maturin的manylinux参数生成兼容容器系统的包：

   maturin build --release --manylinux 2014  # 根据目标容器系统选择对应manylinux版本
   

3. 补充容器系统依赖
   Rust编译的wheel可能依赖系统库（如libssl、libgcc等），本地环境已存在但容器镜像缺失，以Debian/Ubuntu容器为例：

   apt-get update && apt-get install -y libssl-dev libgcc-s1
   

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