一文带你搞懂Python中__init__.py到底是什么

目录

• 先搞懂 Python 模块（module）
• Python 包（package）是啥？
• 那么 __init__.py 到底是干嘛的？
• 1.明确标记目录为 Python 包
• 2.让包能像模块一样被导入
• __init__.py 还能干点啥
• 1. 动态导入子模块
• 2. 控制对外暴露的模块
• 3. 懒加载（Lazy Import）
• 4. 做版本控制
• 5. 隐藏内部实现
• 结尾

朋友们，今天我们来聊聊 Python 里一个低调却至关重要的文件——__init__.py。

说实话，这玩意儿刚开始学 Python 时，很多人（包括当年的我）都是一脸懵：“这啥？删了会咋样？”

有些人可能听说过它是“包的标志”，也有人觉得它“没啥大用，可以忽略”，更有甚者以为它“只是个装样子的文件”。今天，我们就来彻底搞清楚 __init__.py 到底是干啥的，以及它如何影响 Python 项目的结构和运行。

在聊 __init__.py 之前，我们得先弄清楚 Python 里的 模块 和 包 这两个概念。

模块（module）：简单来说，就是一个 .py 文件，里面写了一些函数、类或者变量。

比如，有个叫 math_tools.py 的文件，里面有一堆数学工具函数，那它就是个模块。

# math_tools.py
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

然后，我们可以在别的 Python 文件里这样用它：

import math_tools

print(math_tools.add(3, 5))  # 输出 8

这就是 模块的基本用法，没啥难的，对吧？

如果你写的模块越来越多，代码量越来越大，就得想办法组织它们。这时候，Python 里的 包（package） 就派上用场了。

包（package）：一个 文件夹，里面包含多个模块（.py 文件）。

在 Python 3.3 之前，如果要让一个目录被识别为 Python 包，必须在里面创建 __init__.py 文件。但从 Python 3.3 开始，即使没有 __init__.py，Python 也能识别它是一个包（称为“命名空间包”）。

不过，大部分实际项目 依然建议添加 __init__.py，因为它可以：

✅ 明确这个文件夹是一个包，避免某些工具（如打包工具）识别错误。

✅ 允许在包初始化时执行特定代码，比如自动导入子模块。

✅ 让导入行为更加可控，避免意外的命名冲突。

比如，咱们有个 math_utils 目录，里面放了几个数学相关的模块：

math_utils/     # 这个文件夹就是一个包
│── __init__.py
│── basic.py
│── advanced.py

其中，basic.py 和 advanced.py 分别是两个模块，而 __init__.py 可以用来 自定义包的导入行为。

虽然 __init__.py 不再是创建包的 必需 条件，但它依然是 Python 项目里一个重要的组件。

它的主要作用有 两个：

如果 __init__.py 存在，Python 解析器就会知道：“这个目录是个 Python 包，而不是普通文件夹。”

即使 Python 3.3+ 之后不强制要求 __init__.py，但加上它可以：

✅ 避免 Python 解释器在某些情况下误认为这是普通目录。

✅ 兼容旧版本 Python，让代码能在不同环境中运行得更稳定。

✅ 让某些工具（如 pytest、mypy）更好地识别项目结构。

如果 __init__.py 里什么都不写，那它的作用只是个“标志”。但如果我们在 __init__.py 里加点代码，它就能 自定义包的导入行为。

示例 1：让包直接暴露子模块

# math_utils/__init__.py
from .basic import add, subtract
from .advanced import power

这样，我们就可以直接 import 整个 math_utils，而不需要写 .basic 或 .advanced 了：

import math_utils

print(math_utils.add(2, 3))  # 输出 5
print(math_utils.power(2, 3))  # 假设 advanced 里有个 power 函数

等于说，__init__.py 让 包变得像一个大模块 一样，外部不需要知道里面的模块结构，直接用就行。

示例 2：包初始化操作

__init__.py 还能在包被导入时执行一些初始化操作，比如加载配置、设置日志等：

# math_utils/__init__.py
print("数学工具包加载成功！")  # 只要 import 这个包，就会执行这行代码

大厂的 Python 项目里，__init__.py 还经常被用来做这些事：

在大型 Python 项目中，随着模块越来越多，手动维护__init__.py将变得特别复杂还容易出错，这时候动态导入子模块就成了香饽饽了。
假设我们不知道 math_utils 里具体有哪些模块，可以让 __init__.py 在导入时动态扫描并加载：

# math_utils/__init__.py
import os
import importlib

# 获取当前包的路径
package_path = os.path.dirname(__file__)

# 遍历当前目录下的所有 .py 文件（不包括 __init__.py 本身）
for module in os.listdir(package_path):
    if module.endswith(".py") and module != "__init__.py":
        module_name = module[:-3]  # 去掉 .py 后缀
        importlib.import_module(f"{__name__}.{module_name}")  # 动态导入模块

效果： 这样，当你在别的地方写 import mypackage，所有 mypackage 里的 .py 文件都会自动加载，不用再手动 import 了！

没加动态导入要这么写：

import math_utils.basic
print(math_utils.basic.add(1,2))

#如果直接 import math_utils 会报错AttributeError: module 'math_utils' has no attribute 'basic'

加了动态导入可以这么写：

import math_utils
print(math_utils.basic.add(1,2))

有时候，我们不想让 所有 子模块都被自动导入，而是只暴露一部分给外部用。这时候可以用 __all__ 来 手动控制 允许被 from mypackage import * 访问的模块。

# math_utils/__init__.py
import os
import importlib

package_path = os.path.dirname(__file__)
__all__ = []

for module in os.listdir(package_path):
    if module.endswith(".py") and module != "__init__.py":
        module_name = module[:-3]
        __all__.append(module_name)  # 只暴露在 __all__ 里的模块
        importlib.import_module(f"{__name__}.{module_name}")

效果：

from math_utils import *

print(basic)  # 只有在 __all__ 里的模块能被导入 

如果某些模块比较大，加载它们会影响性能，那可以用 懒加载（lazy import）技术，在需要时才导入，而不是在 import mypackage 时一次性全加载。

# math_utils/__init__.py
import importlib

def lazy_import(name):
    return importlib.import_module(f"{__name__}.{name}")

module1 = lazy_import("basic")

效果：

这样，basic 只有在第一次被使用时才会真正导入，提高了性能！

__init__.py 还能给包加上版本号，让外部代码可以访问：

# math_utils/__init__.py
__version__ = "1.0.0"

然后，在别的地方可以这样用：

import math_utils

print(math_utils.__version__)  # 输出 "1.0.0"

有些模块是“内部用”的，不想让外部访问，怎么办？可以在 __init__.py 里手动控制 对外暴露的内容：

# math_utils/__init__.py
from .basic import add, subtract

__all__ = ["add", "subtract"]  # advanced.py 里的东西就不会被直接 import

这样，外部只能用 math_utils.add()，但 math_utils.advanced 就不让直接访问了。

关于 __init__.py，咱们就聊到这儿！希望这篇文章能帮你彻底搞懂它的作用，今后写 Python 项目时能更自信地使用它。

到此这篇关于一文带你搞懂Python中__init__.py到底是什么的文章就介绍到这了,更多相关Python __init__.py内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• 一文详解Python为什么要写__init__.py
• 详解python __init__.py 和 __all__作用
• 深入理解Python中__init__.py文件
• Python中__init__.py文件的作用
• Python包中__init__.py文件的作用与用法实例详解
• 浅谈Python __init__.py的作用
• Python中__init__.py文件的作用详解