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

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

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

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

先搞懂 Python 模块（module）

在聊 __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）是啥？

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

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

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

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

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

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

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

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

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

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

那么 __init__.py 到底是干嘛的？

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

它的主要作用有 两个：

1.明确标记目录为 Python 包

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

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

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

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

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

2.让包javascript能像模块一样被导入

如果 __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(mathttp://www.chinasem.cnh_utils.power(2, 3))  # 假设 advanced 里有个 power 函数

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

示例 2：包初始化操作

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

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

__init__.py 还能干点啥

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

1. 动态导入子模块

在大型 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)China编程:
    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 maandroidth_utils
print(math_utils.basic.add(1,2))

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__ 里的模块能被导入 

3. 懒加载（Lazy Import）

如果某些模块比较大，加载它们会影响性能，那可以用 懒加载（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 只有在第一次被使用时才会真正导入，提高了性能！

4. 做版本控制

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

# math_utils/__init__.py
__version__ = "1.0.0"

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

import math_utils

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

5. 隐藏内部实现

有些模块是“内部用”的，不想让外部访问，怎么办？可以在 __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内容请搜索China编程(www.chinasem.cn)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程China编程(www.chinasem.cn)！