Python项目里的__init__.py文件到底在忙什么?

你有没有遇到过这种情况？

新建了一个项目文件夹，把功能模块分门别类放好，结果在其他文件里导入时，Python却报错说“找不到模块”。

你盯着屏幕反复检查路径，代码明明就在那里，却像隔着一道无形的墙。

说实话，我之前也是这样。

直到我搞明白了 __init__.py这个文件的作用。

简单来说就是：

它让一堆散乱的Python文件，变成一个井然有序的“包”。

---

往期阅读>>>

Python 为什么会成为AI时代的头部语言

Python 40个常用的列表推导式

Python 50个提高代码开发效率的方法

Python 自动检测服务HTTPS证书过期时间并发送预警

Python 自动化操作Redis的15个实用脚本

Python 自动化管理Jenkins的15个实用脚本，提升效率

Python copyparty搭建轻量的文件服务器的方法

Python 实现2FA认证的方法，提升安全性

Python 封装20个常用API接口，提升开发效率

App2Docker：如何无需编写Dockerfile也可以创建容器镜像

Python 集成 Nacos 配置中心的方法

Python 35个JSON数据处理方法

Python 字典与列表的20个核心技巧

Python 15个文本分析的库，提升效率

Python 15个Pandas技巧，提升数据分析效率

Python 运维中30个常用的库，提升效率

Python调用远程接口的方法

Python 提取HTML文本的方法，提升效率

Python 应用容器化方法：实现“一次部署，处处运行”

Python 自动化识别Nginx配置并导出为excel文件，提升Nginx管理效率

Python 5个常见的异步任务处理框架

Python数据科学常见的30个库

Python 50个实用代码片段，优雅高效

1. 基础作用：给文件夹贴上“可导入”的标签

在Python的世界里，文件夹和包是两回事。

一个普通的文件夹，对Python而言只是个存放文件的容器，它不会主动去里面找模块。但如果你在这个文件夹里放一个__init__.py 文件（哪怕是空的），Python就会恍然大悟：“哦，原来这是一个包（Package），里面的东西是可以被导入的。”

场景：你有一个工具集项目，结构如下：

my_utils/├── math_tools.py   # 包含 add, subtract 函数├── string_tools.py # 包含 capitalize, reverse 函数└── file_tools.py   # 包含 read_file, write_file 函数

如果没有 __init__.py，你在主程序里写 from my_utils.math_tools import add，Python会直接报错 ModuleNotFoundError: No module named 'my_utils'。

解决方案：在 my_utils 文件夹内创建一个 __init__.py 文件。

# my_utils/__init__.py# 这是一个空文件，但它的存在至关重要！

现在，同样的导入语句就能正常工作了。这个空文件就像是一个“门牌”，告诉Python：“这里住着一个叫 my_utils 的包，欢迎来访。”

2. 进阶功能：扮演包的“前台”与“管家”

__init__.py 可不仅仅是个空牌子。你可以在里面写代码，让它发挥更强大的作用。

场景一：简化导入路径，提供清晰API

当你的包越来越复杂，子模块众多时，让使用者记住每个函数的精确路径很麻烦。__init__.py 可以充当“前台”，统一暴露常用功能。

示例代码：

# my_utils/__init__.py# 从各个子模块导入核心函数，集中到包级别from .math_toolsimportadd, multiplyfrom .string_toolsimportcapitalizefrom .file_toolsimportread_file# 可选：定义 __all__ 列表，明确控制“from my_utils import *”时导入的内容__all__ = ['add', 'multiply', 'capitalize', 'read_file']

现在，使用者可以这样导入，非常简洁：

# 在主程序中frommy_utilsimportadd, read_fileresult = add(5, 3)content = read_file('data.txt')

场景二：执行包级初始化

有些设置只需要在包被第一次导入时执行一次，比如加载配置文件、建立数据库连接池、注册插件等。

示例代码：

# my_utils/__init__.pyimportjsonimportloggingprint(f"初始化 my_utils 包...")# 加载包级别的配置try:withopen('my_utils/config.json', 'r') asf:CONFIG = json.load(f)DEFAULT_TIMEOUT = CONFIG.get('timeout', 10)exceptFileNotFoundError:DEFAULT_TIMEOUT = 10print("未找到配置文件，使用默认超时设置。")# 设置包级别的日志器logger = logging.getLogger(__name__)logger.info("my_utils 包初始化完成。")# 同样可以暴露配置和日志器__all__ = ['add', 'read_file', 'DEFAULT_TIMEOUT', 'logger']

当用户第一次运行 import my_utils 时，上述初始化代码会自动执行，为整个包准备好运行环境。

3. 常见误区与避坑指南

结合我踩过的坑，总结几个关键点：

• __init__.py 必须是非空的吗？不一定！对于简单的包，一个空的__init__.py 就足以完成其核心使命——标记包。是否需要添加代码，取决于你是否需要简化导入或进行初始化。

• 所有文件夹都需要它吗？不是！只有那些需要被Python代码导入的文件夹才需要它。比如，存放图片的 assets/、存放文档的 docs/ 文件夹就不需要。而存放源代码的 src/、utils/、models/ 等文件夹通常都需要。

• 名字绝对不能错！它的名字是 __init__.py（两边各两个下划线）。我曾经手误写成 _init_.py 或 init.py，导致调试了半天。Python只认这个标准名字。

• Python 3.3+ 的“命名空间包”是的，Python 3.3之后引入了命名空间包，允许没有 __init__.py 的文件夹在某些情况下被导入。但为了兼容性和项目结构清晰，尤其是对于需要分发和共享的包，明确地加上 __init__.py 是最佳实践，能避免许多意想不到的问题。

写在最后

__init__.py 就像是一个项目的隐形管家。它不张扬，甚至常常被忽略，但正是它默默定义了包的边界，打理着对外的门面，并确保包在“上岗”前准备就绪。

理解它，用好它，你的Python项目结构会立刻从“散兵游勇”升级为“纪律部队”。

代码组织的本质，不是把文件堆在一起，而是让它们成为一个有机的整体。

下次新建文件夹时，别忘了给这位“隐形管家”留个位置。

https://ima.qq.com/wiki/?shareId=f2628818f0874da17b71ffa0e5e8408114e7dbad46f1745bbd1cc1365277631c