Python 包初始化代码的正确放置位置

__init__.py 必须放在希望被当作python包导入的最外层目录中，如 mypackage/ 下；空文件即可生效，但若编写内容需避免耗时操作与循环导入，并合理使用 __all__ 和子模块导入来控制接口。

__init__.py 应该放在哪个目录里

它必须出现在你想让 Python 把那个目录当作一个包来导入的最外层目录下。不是所有目录都要放，只在你明确要 import mypackage 或 from mypackage import something 的那个目录里放。

常见错误现象：ModuleNotFoundError: No module named 'mypackage'，往往是因为 __init__.py 缺失，或者位置比你预期的高/低了一层。

• 如果你运行 python main.py，而 main.py 试图 import utils，那 utils/ 目录下就得有 __init__.py
• 如果项目结构是 src/mypackage/__init__.py，但你没把 src 加进 PYTHONPATH 或没用 -m 方式运行，Python 就找不到 mypackage
• 空文件即可生效；内容可以为空，不需要写任何代码

__init__.py 里写什么才不算多余

它不是必须写东西，但一旦写了，就会影响包的公开接口和导入行为——这点容易被忽略。

使用场景：你想控制 from mypackage import * 暴露哪些名字，或想简化嵌套模块的导入路径。

立即学习“Python免费学习笔记（深入）”；

• 用 __all__ = ['Client', 'Config'] 明确限定 from mypackage import * 可导入的内容
• 在 __init__.py 中 from .core import Client，就能让用户直接 from mypackage import Client，而不是 from mypackage.core import Client
• 避免在 __init__.py 中做耗时操作（比如读配置、连数据库），因为只要导入包就会执行它
• 别在 __init__.py 里循环导入同级模块，容易触发 ImportError: cannot import name 'X' from partially initialized module

Python 3.3+ 还需要 __init__.py 吗

技术上，PEP 420 引入了隐式命名空间包，允许没有 __init__.py 的目录被识别为包——但仅限于特定场景，不能当作默认做法。

性能 / 兼容性影响：不放 __init__.py 会让包失去明确边界，ide 和静态检查工具（如 mypy、pylint）可能无法正确解析相对导入或类型提示。

• 如果你的包要发布到 PyPI，必须包含 __init__.py，否则安装后无法导入
• 多个分散目录组成一个逻辑包（比如插件目录）时，才可以考虑不用 __init__.py，但这是例外，不是常规
• 团队协作中，显式优于隐式；少一个 __init__.py 带来的“简洁”，远不如它带来的可维护性损失

setup.py / pyproject.toml 里怎么配合包初始化

构建配置文件不会自动帮你补 __init__.py，但它会决定 Python 最终从哪找包——这两者必须对齐。

常见错误现象：本地能 import mypkg，打包后安装却报错，大概率是 setuptools.find_packages() 没扫到你的包目录，或者 packages 列表漏了。

• 用 find_packages(where="src") 时，确保 src/mypkg/__init__.py 存在，且 src 是实际根目录
• pyproject.toml 中 [project] packages = ["mypkg"] 要和磁盘上 mypkg/__init__.py 的路径严格对应
• 不要依赖 package-dir 魔改路径来绕过 __init__.py 缺失问题，这会让调试和 IDE 支持变差

真正容易被忽略的是：包初始化不是“有没有”的问题，而是“谁在什么时候、以什么方式触发了它的加载”。哪怕只差一层目录、一个路径配置、一次没注意的 cd，__init__.py 就形同虚设。