如何使用 pip 安装本地 Python 项目并自动识别嵌套子包

本文详解如何通过 `pip install -e .` 正确安装采用“ad-hoc 布局”的本地 python 项目，解决 `find_packages(where='mypkg')` 报错及子包不可导入的问题，关键在于配置 `package_dir` 映射源码根目录与实际包路径。

在开发多层嵌套的本地 Python 项目时（如 mypkg/subpkg1/, mypkg/subpkg2/），常希望仅执行一条命令（如 pip install -e .）即可完成可编辑安装，并让所有带 __init__.py 的子目录自动作为可导入子包。但若项目结构为典型的 ad-hoc layout（即包代码位于子目录 mypkg/ 下，而非与 setup.py 同级），直接使用 find_packages() 很容易失败——典型报错如：

error: package directory 'subpkg1' does not exist

该错误并非因为目录真实缺失，而是 setuptools.find_packages() 默认在当前目录（即 project_root_directory）下查找包，而你的包实际位于 mypkg/ 子目录中。此时，仅靠 find_packages(where='mypkg') 是不够的：它能发现 mypkg.subpkg1 等包，但 setuptools 仍会尝试从项目根路径解析模块路径，导致路径映射错位。

✅ 正确解法是同时声明 package_dir，显式告诉 setuptools：“当导入 mypkg 及其子包时，请从 mypkg/ 目录下加载源码”。

修改你的 setup.py 如下：

from setuptools import setup, find_packages

setup(
    name="Code",
    author="Me",
    author_email="me@example.com",
    description="My local Python project",
    package_dir={"": "mypkg"},  # ? 关键！将空字符串（即顶层包名）映射到 'mypkg' 目录
    packages=find_packages(where="mypkg"),  # 在 mypkg/ 下自动发现所有子包
    python_requires=">=3.6",
)

? 补充说明：package_dir={"": "mypkg"} 表示“所有未指定前缀的包（包括 mypkg 本身）均从 mypkg/ 目录读取”。这样 find_packages(where="mypkg") 才能与安装时的路径解析逻辑对齐。

✅ 安装验证：

pip install -e .

安装成功后，即可在 Python 中正常导入：

from mypkg import module          # ✔️ 主包
from mypkg.subpkg1 import module1 # ✔️ 子包
import mypkg.subpkg2.module2      # ✔️ 深层嵌套

⚠️ 注意事项：

__init__.py 文件必须存在且非空（至少含 __all__ 或 pass），否则 find_packages() 会跳过该目录；
若使用 pyproject.toml（推荐现代项目），应改用 setuptools 配置块，并保留等效逻辑（[project] + [tool.setuptools]）；
IDE（如 VS Code、PyCharm）可能因缓存延迟无法立即支持 tab 补全，重启 Python 解释器或刷新环境后通常可恢复；
避免在 packages 中手动列出子包名（如 ["mypkg", "mypkg.subpkg1"]），这会绕过自动发现机制，丧失可维护性。

总结：package_dir={"": "mypkg"} 是 ad-hoc 布局下实现一键可编辑安装与完整子包可见性的核心配置。它桥接了物理目录结构与 Python 包命名空间，是本地开发中兼顾简洁性与规范性的最佳实践。

# python # ai # pycharm # vs code

返回目录在线咨询

上一篇：Easyui笔记2：实现datagrid多行删除的示例代码
下一篇：怎样制作网站保存视频到相册,2345电脑网页视频怎么保存？

您的项目需求

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

全网整合营销服务商

如何使用 pip 安装本地 Python 项目并自动识别嵌套子包

您的项目需求