如何在Python包中包含whl文件并通过pyproject.toml作为依赖安装

当你需要将未发布到PyPI或公开仓库的本地依赖（如libs/下的.whl/.zip）随自己的包一同安装时，可以通过以下两种方式配置pyproject.toml结合setuptools实现：

方法一：用find-links指定本地依赖目录 #

适合管理多个本地依赖的场景，配置更简洁：

[project]
name = "my-package"
version = "0.1.0"
dependencies = [
    "package_name",  # 填写本地包的实际名称，需与.whl/.zip中的包名一致
    # 其他常规依赖项...
]

[tool.setuptools.find-links]
paths = ["./libs/"]  # 指定本地依赖所在的目录

方法二：直接在依赖列表中使用相对路径URI #

针对单个本地依赖，可直接在dependencies中用PEP 508规范的相对路径写法（注意不要用file:///开头的绝对路径格式）：

[project]
name = "my-package"
version = "0.1.0"
dependencies = [
    # ...其他依赖
    "package_name @ file:./libs/package_name.whl"  # 替换为你的.zip/.whl文件路径
]

必须步骤：确保本地依赖被打包进分发包 #

无论用哪种方法，都要配置打包工具将libs/下的依赖文件包含到你的包分发中，否则用户安装时会找不到文件：

方式1：通过pyproject.toml配置 #

[tool.setuptools.include-package-data]
true = true

[tool.setuptools.package-data]
"" = ["libs/*.whl", "libs/*.zip"]  # 匹配libs目录下的所有目标文件

方式2：使用MANIFEST.in文件 #

在项目根目录创建MANIFEST.in，写入：

include libs/*.whl
include libs/*.zip

验证安装效果 #

配置完成后，可测试两种安装场景：

• 本地可编辑安装：执行pip install --editable .
• 打包后安装：先运行python -m build生成dist目录下的包，再执行pip install dist/my_package-0.1.0-py3-none-any.whl

两种场景下，你的包和对应的本地依赖都应该被自动安装。

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