pyproject.toml 的 [dependencies] 必须显式列出所有直接 import 的运行时依赖，pip 不推断 import；漏写致 ModuleNotFoundError；子依赖由所依赖库自动声明，无需手动添加；numpy 等建议锁小版本如 "numpy>=1.21.0,
pyproject.toml 中的 [dependencies] 必须显式列出所有运行时依赖
PyPI 安装器（如 pip）不会自动推断你代码里 import 了什么，只认配置文件里写死的依赖项。漏写会导致用户安装后运行报 ModuleNotFoundError。
常见错误是只写了主库，却忘了它的子依赖——比如用了 requests 的 Session 和 urllib3 的重试逻辑，但没声明 urllib3；其实不用手动加，requests 自己的 pyproject.toml 已声明它，pip 会递归安装。真正要写的是你直接 import 的包。
-
numpy、pandas这类底层库建议锁小版本号，例如"numpy>=1.21.0,，避免 ABI 不兼容 - 用
^（Poetry 默认）等价于>=x.y.z,，适合语义化版本良好的库（如 typer） - 避免写
*或空字符串，这会让 pip 安装最新版，极易引发运行时 break
setup.py 里的 install_requires 不能靠 find_packages() 自动补全
find_packages() 只负责发现项目中哪些目录是 Python 包，和依赖无关。很多人误以为只要把代码放对位置，setuptools 就能“猜出”要装啥，实际完全不会。
如果你的模块里有 from google.cloud import storage，就必须在 install_requires 里写 "google-cloud-storage"，否则用户 pip install . 后一跑就崩。
- 不要把开发依赖（如
pytest、mypy）混进install_requires，它们该放在extras_require或[dev-dependencies]里 - 条件依赖要写清楚，比如 Windows 下才需要
pywin32：'pywin32; platform_system == "Windows"' - 如果依赖包在 PyPI 上名字和 import 名不一致（如
python-dotenv→dotenv），以 PyPI 名为准
打包时依赖未被包含进 wheel，大概率是 setup.py 没生效或 pyproject.toml 覆盖了它
当前主流构建后端（如 setuptools >=61.0 或 build 工具）默认优先读 pyproject.toml。如果你同时有 setup.py 和 pyproject.toml，但后者没写 [project.dependencies]，那 setup.py 的 install_requires 就会被忽略。
验证方法：运行 python -m build --wheel 后，解压生成的 .whl 文件，检查根目录下 metadata.json 或 WHEEL 文件里的 Requires-Dist 字段是否匹配你预期的依赖列表。
- 用 Poetry 构建时，确保
poetry build前已执行poetry lock，否则poetry.lock未更新，wheel 里可能含旧依赖 - 用
build工具时，若pyproject.toml中指定了build-backend = "setuptools.build_meta"，则setup.py仍可被读取，但必须保证两者依赖声明一致，否则行为不可控
动态导入或插件机制的依赖容易被漏掉
像 importlib.import_module("xxx")、pkg_resources.load_entry_point、或通过字符串名加载的模块（如 Celery 的 task_routes 配置），静态分析工具（包括 pip、Poetry、pipdeptree）都看不到，自然不会自动加入依赖列表。
这类情况必须人工判断并显式声明，否则用户环境里缺包，报错位置往往远离真实问题点（比如崩在 __init__.py 的 load_plugins() 里，而不是你写的 import 行）。
- 如果插件来自第三方包（如
sqlalchemy的方言插件psycopg2），按需声明，别一股脑全写进去 - 若插件是你自己维护的子包（如
mylib.plugins.s3），确保它被packages或find_packages()包含，且其依赖单独列在install_requires或对应pyproject.toml段落中 - CI 流程里建议加一条测试：新建干净虚拟环境 →
pip install your-package→python -c "import your_package; your_package.init_plugins()"，提前暴露缺失依赖
依赖声明不是“写完就完”，它直接决定下游能否成功导入。最隐蔽的问题往往出现在跨平台插件、运行时加载、以及混合使用 Poetry / setuptools / PEP 517 构建后端的项目里——这些地方没有警告，只有用户报错时你才意识到漏了一行 "pydantic>=2.0"。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
