如何让setup.py忽略PyPI同名包但检查本地依赖已安装？

针对你遇到的本地API与PyPI同名包的依赖冲突问题，以下是几种比仅靠文档说明更规范的解决方案：

1. 在setup阶段用pkg_resources检查依赖存在性与合法性 #

直接在setup.py开头加入检查逻辑，不在install_requires中列出该同名包（避免pip自动拉取PyPI版本），强制要求用户提前安装本地包，并可验证安装的是否为正确的本地版本。

示例代码：

from setuptools import setup
from pkg_resources import get_distribution, DistributionNotFound

try:
    # 检查本地是否已安装目标包
    get_distribution("your-package-name")
    # 可选：验证包的本地专属功能，确保不是PyPI版本
    import your_package_name
    assert hasattr(your_package_name, "local_only_api"), "安装的不是本地版本的your-package-name"
except DistributionNotFound:
    raise RuntimeError("请先手动安装本地版本的your-package-name：`pip install -e /path/to/local/package`")
except AssertionError as e:
    raise RuntimeError(str(e))

# 正常编写包的setup配置
setup(
    name="your-lab-package",
    install_requires=[
        # 这里只放其他无冲突的依赖
    ],
    # ... 其他必要参数（版本、作者等）
)

这种方式既符合Python打包规范，又能提前拦截错误，明确引导用户操作。

2. 利用版本号限制拦截PyPI包（需本地包有独特版本） #

如果你的本地API包有和PyPI版本完全不同的版本标识（比如本地用1.0.0.dev0，PyPI上是1.0.0及正式版），可以在install_requires中指定严格版本匹配，让pip无法在PyPI找到对应版本，从而报错提示用户手动安装：

setup(
    # ... 其他配置
    install_requires=[
        "your-package-name==1.0.0.dev0",
        # 其他正常依赖
    ]
)

注意：这种方案依赖版本号的唯一性，若后续PyPI版本更新到相同标识会失效，适合本地包长期使用固定开发版号的场景。

3. 基于PEP 621的动态依赖检查（现代打包方案） #

如果你的项目采用pyproject.toml（PEP 621规范）管理打包配置，可以配合动态依赖实现检查：

1. 在pyproject.toml中声明动态依赖：

[project]
name = "your-lab-package"
dynamic = ["dependencies"]
# ... 其他基础配置（版本、作者等）

2. 在setup.py中实现依赖检查逻辑，动态生成依赖列表：

from setuptools import setup
from pkg_resources import get_distribution, DistributionNotFound

def resolve_dependencies():
    base_deps = [
        # 其他无冲突的依赖
    ]
    try:
        get_distribution("your-package-name")
        import your_package_name
        assert hasattr(your_package_name, "local_api_feature")
    except (DistributionNotFound, AssertionError):
        raise RuntimeError("请先安装本地版本的your-package-name")
    return base_deps

setup(
    dependencies=resolve_dependencies(),
    # ... 其他参数
)

最优方案推荐 #

第一种方案是最可靠的：通过pkg_resources提前检查依赖存在性并验证版本合法性，同时不在install_requires中添加该包，从根源上避免pip去PyPI拉取同名包，既规范又能明确引导用户正确操作。

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