如何正确配置本地 Python 项目以支持可编辑安装及自动发现子包

本文详解如何通过 pip install -e . 正确安装本地 python 项目，并使其自动识别嵌套子包（如 mypkg.subpkg1），关键在于正确设置 package_dir 映射与 find_packages() 的配合使用。

在采用“ad-hoc 布局”（即源码目录不与包名同名，例如顶层为 project_root/，实际包位于 project_root/mypkg/）的本地 Python 项目中，直接使用 pip install -e . 往往无法正确导入子模块——即使所有 __init__.py 文件齐全、路径结构合规。典型症状包括：find_packages() 报错 package directory 'subpkg1' does not exist，或虽安装成功但 import mypkg.subpkg1 失败。

根本原因在于：find_packages() 默认在当前目录（.）下搜索带 __init__.py 的包，而你的包实际位于 mypkg/ 子目录中。若未显式声明源码根目录映射，setuptools 会错误地将 mypkg/subpkg1 解析为相对于项目根的 ./subpkg1，从而导致路径查找失败。

✅ 正确解法是：同时配置 package_dir 和 find_packages()，明确告知 setuptools “包逻辑名称” 与 “物理路径” 的对应关系：

# setup.py
from setuptools import setup, find_packages

setup(
    name="Code",
    author="Me",
    author_email="Me",
    description="Code",
    package_dir={"": "mypkg"},  # ✅ 关键：空字符串 "" 表示根包名（即 mypkg），映射到 ./mypkg/
    packages=find_packages(where="mypkg"),  # ✅ 在 mypkg/ 下递归发现所有子包
    python_requires=">=3.6",
)

? package_dir={"": "mypkg"} 的含义是：所有未显式命名的包（即顶层包 mypkg 及其全部子包）均从 mypkg/ 目录下加载。这使 find_packages(where="mypkg") 能正确遍历 mypkg/subpkg1/、mypkg/subpkg2/ 等真实路径。

安装后验证：

pip install -e .
python -c "from mypkg.subpkg1 import module1; print('Success!')"

⚠️ 注意事项：

不要混用 setup.py 和 pyproject.toml 中的构建配置：若已存在 pyproject.toml（尤其含 [build-system]），优先推荐迁移到现代声明式配置（见下方替代方案）；
IDE 自动补全可能滞后：如 VS Code 或 PyCharm 未立即识别新包结构，重启语言服务器或重新加载工作区即可解决（非代码问题，属环境缓存）；
__init__.py 缺失 = 非包目录：确保每个希望被导入的子目录（如 subpkg1/）均含 __init__.py（可为空），否则 find_packages() 会跳过它；
现代推荐（Python 3.8+）：可改用 pyproject.toml 实现等效配置，更简洁且符合 PEP 517/518 标准：

# pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
build-backend = "setuptools.build_meta"

[project]
name = "Code"
authors = [{name = "Me", email = "Me"}]
description = "Code"
requires-python = ">=3.6"

[project.urls]
Homepage = "https://example.com"

[tool.setuptools]
package-dir = {"" = "mypkg"}           # 等效于 setup.py 中的 package_dir
packages = {find = {where = ["mypkg"]}} # 等效于 find_packages(where="mypkg")

至此，执行 pip install -e . 即可完成可编辑安装，所有 mypkg.* 子模块均可直接导入与使用，真正实现“一次配置，全树可见”。

# python # ai # pycharm # vs code

返回目录在线咨询

上一篇：微信小程序 MD5加密登录密码详解及实例代码
下一篇：共享主机与VPS：哪种网站服务器能提供更好的性价比？

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

全网整合营销服务商

如何正确配置本地 Python 项目以支持可编辑安装及自动发现子包

您的项目需求