如何为Python包实现子模块的动态按需安装功能？

我太懂你这种纠结了——不想拆分仓库把事情复杂化，又想让用户能按需安装不浪费资源，之前踩过的那些坑（改find_packages、自定义cmdclass）我也碰过，确实都不是最优解。给你两个层级的专业方案，从标准官方方案到变通的进阶技巧，你可以根据需求选：

一、官方标准方案：用extras_require管理可选依赖（首推） #

这是Python生态里最通用、最被认可的方案，核心思路是：子模块本身会随主包全量安装，但每个子模块的额外依赖通过extras_require绑定，用户可以通过pip install package[submodule1]来安装主包+submodule1的依赖；如果用户没装这个extra，导入submodule1时会给出清晰的提示，引导他们安装对应依赖。

具体操作步骤 #

1. 在setup.py或setup.cfg里配置extras_require
   如果你用setup.py，可以这么写：

   from setuptools import setup, find_packages
   
   setup(
       name="your-package",
       version="1.0.0",
       packages=find_packages(),
       extras_require={
           "submodule1": ["requests>=2.25.0"],
           "submodule2": ["pandas>=1.3.0"],
           "submodule3": ["numpy>=1.21.0"],
           "submodule4": ["matplotlib>=3.4.0"],
           "all": ["requests>=2.25.0", "pandas>=1.3.0", "numpy>=1.21.0", "matplotlib>=3.4.0"]
       }
   )
   

   更推荐用现代的setup.cfg写法，可读性和维护性更好：

   [metadata]
   name = your-package
   version = 1.0.0
   
   [options]
   packages = find:
   
   [options.extras_require]
   submodule1 = requests>=2.25.0
   submodule2 = pandas>=1.3.0
   submodule3 = numpy>=1.21.0
   submodule4 = matplotlib>=3.4.0
   all =
       requests>=2.25.0
       pandas>=1.3.0
       numpy>=1.21.0
       matplotlib>=3.4.0
   

2. 在子模块里添加依赖检查逻辑
   比如在package/submodule1/__init__.py里加一段导入检查，确保用户没装依赖时能得到明确提示：

   try:
       import requests
   except ImportError:
       raise ImportError(
           "submodule1 requires the 'requests' dependency. "
           "Install it with: pip install your-package[submodule1]"
       )
   
   # 下面是submodule1的正常业务代码
   

这个方案的优势 #

• 完全符合Python包规范，pip官方原生支持，没有兼容性隐患
• 不需要改动现有包结构，维护成本极低
• 用户体验友好，错误提示清晰，不会让用户摸不着头脑

二、进阶变通：实现子模块文件的按需安装（仅特殊场景用） #

如果你确实需要让用户只安装特定子模块的文件（而不是全量安装所有子模块），这个需求其实和Python wheel的预构建机制冲突——wheel会把所有包文件打包进去，安装时无法动态筛选。但可以通过以下方式变通，不过我真的不推荐，除非是万不得已的特殊场景：

方法1：结合find_packages和环境变量 #

在setup.py里通过读取环境变量来决定要包含哪些子包：

from setuptools import setup, find_packages
import os

# 读取用户指定的子模块，默认全量安装
selected_submodules = os.environ.get(
    "PACKAGE_SUBMODULES", 
    "submodule1,submodule2,submodule3,submodule4"
).split(",")
# 构造要包含的包列表：主包 + 选中的子包
packages = ["package"] + [f"package.{sm}" for sm in selected_submodules]

setup(
    name="your-package",
    version="1.0.0",
    packages=packages
)

用户安装时需要先设置环境变量，并且必须用--no-binary :all:跳过wheel，直接从源码构建：

# 只安装submodule1和submodule3
export PACKAGE_SUBMODULES=submodule1,submodule3
pip install your-package --no-binary :all:

方法2：用extras_require配合动态包筛选 #

把extra和子模块绑定，在setup.py里解析用户传递的extra参数来筛选要包含的子包：

from setuptools import setup, find_packages
import sys

# 解析用户指定的extra参数
selected_submodules = []
for arg in sys.argv:
    if arg.startswith("[") and arg.endswith("]"):
        selected_submodules = arg[1:-1].split(",")

# 构造包列表
if selected_submodules:
    packages = ["package"] + [f"package.{sm}" for sm in selected_submodules]
else:
    # 默认全量安装所有子模块
    packages = find_packages()

setup(
    name="your-package",
    version="1.0.0",
    packages=packages,
    extras_require={
        "submodule1": [],
        "submodule2": [],
        "submodule3": [],
        "submodule4": [],
    }
)

用户安装时需要这样操作：

pip install your-package[submodule1] --no-binary :all:

这种变通方案的问题 #

• 必须让用户配合使用--no-binary :all:，否则预构建的wheel还是会包含所有文件，等于白搭
• 兼容性差，不同pip版本传递参数的方式可能有变化，容易出问题
• 维护成本高，需要处理各种边缘情况，后续升级pip或setuptools都可能踩坑

最后总结 #

优先选第一种extras_require的官方方案，这是Python社区的共识，既简单又可靠。拆分仓库或者搞复杂的动态安装逻辑，只会给自己和用户添麻烦，完全没必要。

内容来源于stack exchange