Python 命名改写机制的实际效果

__name__ 是解释器自动赋值的只读字符串：直接运行时为 "__main__"，被导入时为完整模块名（如 "utils.helpers"）；它与 __package__ 共同决定相对导入行为，不可用于动态导入或别名控制。

Python 的 __name__ 属性在模块导入时到底怎么变？

它不是“被改写”，而是由解释器在加载模块时**自动赋值**的字符串，值取决于模块如何被启动。直接运行一个文件，__name__ 是 "__main__"；被 import 进来，就是它的模块名（不含 .py）。

常见错误现象：if __name__ == "__main__": 里写的测试代码，在被其他模块 import 后意外执行了——那说明你可能在模块顶层写了可执行语句，没包进这个判断里。

• 模块路径为 utils/helpers.py，被 import utils.helpers 后，utils.helpers.__name__ 是 "utils.helpers"，不是 "helpers"
• 如果用 from utils.helpers import something，helpers.py 文件仍会被执行一次，__name__ 仍是 "utils.helpers"，不是 "__main__"
• __name__ 是只读属性，手动赋值（如 __name__ = "xxx"）不会影响导入行为，只会覆盖当前作用域的变量

为什么 __name__ 不能用来做模块别名或动态导入控制？

因为它的值是解释器决定的，不是你定义的“名称”。想换名？得靠 import ... as 或者 sys.modules 手动注册，但后者风险高、不推荐。

使用场景：有人试图用 if __name__.endswith("test"): 来区分测试模块，这不可靠——模块名完全取决于 import 路径，和文件名无关。比如 tests/conftest.py 被 pytest 导入时，__name__ 是 "conftest"，不是 "tests.conftest"（取决于是否在包内正确声明 __init__.py）。

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

Molica AI

一款聚合了多种AI工具的一站式创作平台

下载

• 动态导入应使用 importlib.import_module()，传入字符串模块名，而不是拼 __name__
• __name__ 在 exec() 或 compile() 的上下文中会是 "<string>"</string> 或你指定的字符串，但这和模块系统无关
• 打包工具（如 PyInstaller）会重置部分模块的 __name__，比如启动脚本可能变成 "__main__"，但子模块名不变

__name__ 和 __package__ 配合才能准确定位相对导入

相对导入（from . import xxx）依赖两者：解释器用 __name__ 推导当前模块的完整路径，再用 __package__ 确认包层级。缺一不可。

常见错误现象：报 SystemError: Parent module '' not loaded, cannot perform relative import——基本是因为该文件不是作为包内模块被导入的（比如直接 python mypkg/mymod.py），此时 __package__ 是 None，__name__ 是 "__main__"，解释器无法推导上级包。

• 确保用 python -m mypkg.mymod 运行，而非 python mypkg/mymod.py
• 包目录下必须有 __init__.py（哪怕空），否则 __package__ 为空字符串，相对导入失败
• __package__ 为空字符串时，__name__ 是模块名（如 "mymod"）；在子包中，__package__ 是 "mypkg.subpkg"，__name__ 是 "mypkg.subpkg.mymod"

调试时怎么快速验证 __name__ 和 __package__ 的实际值？

别猜，直接打印。尤其在 IDE 中右键“Run”和终端里 python -m 行为不一致时，这是最省时间的办法。

示例（放在模块顶部即可）：

print(f"__name__: {__name__}")
print(f"__package__: {__package__}")
print(f"__file__: {__file__}")

注意：__file__ 在某些环境（如 frozen 可执行文件、Jupyter cell）里可能不存在或不指向源码，但它和 __name__ 没有绑定关系——别用 __file__ 去反推 __name__。

• 在 __main__.py 中，__name__ 是 "__main__"，但 __package__ 是包名（如 "mypkg"），这是支持 python -m mypkg 的关键
• 单元测试框架（如 pytest）会临时修改 sys.modules，导致某些模块的 __name__ 显示异常，此时应以 __file__ 和实际 import 路径为准