Setuptools自定义install命令动态安装指定子包问题解决

参数不生效是三个典型的setuptools自定义命令写法错误导致的：

• 自定义选项声明不符合规范：user_options里的长选项名如果需要接收参数值，必须在末尾加=，否则setuptools会把它识别为不需要传值的布尔开关，传入的参数值会被直接丢弃
• 没有实现finalize_options方法或没有调用父类的finalize_options：setuptools的命令行参数赋值逻辑是在finalize_options阶段执行的，跳过这一步在initialize_options里初始化的属性永远是默认值None
• 示例命令里参数末尾多了冗余逗号，会导致子包名匹配失败，属于额外的传参错误

首先确认项目结构符合预期：

parent_package/
├── base/
│   └── __init__.py
├── src/
│   ├── mypkg1/
│   │   └── __init__.py
│   ├── mypkg2/
│   │   └── __init__.py
├── requirements.txt
└── setup.py

以下是可直接运行的setup.py代码，核心逻辑是始终安装base包，未传参时默认安装src下全部子包，传参时仅安装指定子包：

import os
from setuptools import setup
from setuptools.command.install import install

# 自动扫描src目录下的合法子包
SRC_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "src")
AVAILABLE_SUBPKGS = [
    entry.name for entry in os.scandir(SRC_ROOT)
    if entry.is_dir() and os.path.exists(os.path.join(entry.path, "__init__.py"))
]

class CustomInstallCommand(install):
    # 声明自定义命令选项，长选项末尾加=表示需要接收参数值
    user_options = install.user_options + [
        ("subpackage=", None, "指定src目录下要安装的子包，多个用逗号分隔，不传则安装全部子包"),
    ]

    def initialize_options(self):
        super().initialize_options()
        self.subpackage = None

    def finalize_options(self):
        super().finalize_options()
        # 解析、校验传入的子包参数
        if self.subpackage:
            self.selected_pkgs = [
                pkg.strip() for pkg in self.subpackage.split(",")
                if pkg.strip()
            ]
            invalid_pkgs = [p for p in self.selected_pkgs if p not in AVAILABLE_SUBPKGS]
            if invalid_pkgs:
                raise ValueError(
                    f"指定的子包不存在：{', '.join(invalid_pkgs)}，可选子包为：{', '.join(AVAILABLE_SUBPKGS)}"
                )
        else:
            self.selected_pkgs = AVAILABLE_SUBPKGS

    def run(self):
        # 组装最终安装包列表：始终包含base包，追加选中的src子包
        final_packages = ["base"]
        final_packages.extend([f"src.{pkg}" for pkg in self.selected_pkgs])
        # 覆盖setuptools的包配置，确保安装流程识别目标包
        self.distribution.packages = final_packages
        super().run()

# 生成包路径映射
package_dir_map = {"base": "base"}
for pkg in AVAILABLE_SUBPKGS:
    package_dir_map[f"src.{pkg}"] = f"src/{pkg}"

setup(
    name="parent_package",
    version="1.0.0",
    cmdclass={"install": CustomInstallCommand},
    package_dir=package_dir_map,
    install_requires=[
        req.strip() for req in open("requirements.txt", "r", encoding="utf-8")
        if req.strip() and not req.startswith("#")
    ]
)

安装命令不要在参数末尾加冗余逗号：

• 安装base包+指定单个子包mypkg1：
  pip install . --install-option="--subpackage=mypkg1"
• 安装base包+多个子包mypkg1、mypkg2：
  pip install . --install-option="--subpackage=mypkg1,mypkg2"
• 不传--subpackage参数时，默认安装base包+src下所有子包：
  pip install .

• pip 23.1+版本已经将--install-option标记为废弃，如果不需要兼容旧版本，可以改用环境变量传参的方式实现相同逻辑，上述代码在现有兼容版本pip中可正常运行
• src下每个子包目录必须包含__init__.py文件，否则不会被识别为合法Python包
• 如果需要支持wheel格式分发安装，不要用自定义install命令方案（wheel安装不会执行setup.py中的install逻辑），该场景建议改用extras_require实现可选包安装。

内容的提问来源于stack exchange，提问作者Piyush S. Wanare