Python .pyc 文件的生成与失效机制-Python教程

Python 为什么自动生成 .pyc 文件

Python 解释器在首次导入模块时，会将 .py 源码编译为字节码并缓存为 .pyc 文件，目的是避免重复编译、加快后续导入速度。这个过程由 import 触发，不是运行脚本（如 python main.py）时默认发生的——除非该脚本被当作模块被其他文件 import。

生成位置取决于 Python 版本：
• Python 3.2+ 使用 __pycache__ 目录，文件名形如 module.cpython-311.pyc；
• Python 2 或手动启用 -B 时可能直接生成同目录下的 module.pyc。

• .pyc 文件不包含源码，只含字节码 + 部分元数据（如源文件路径、时间戳、Python 版本标识）
• 即使源码被删，只要 .pyc 有效且未过期，import 仍可成功（但 traceback 会显示原 .py 路径）
• 若解释器无法写入 __pycache__（权限不足、只读文件系统），则跳过缓存，每次重新编译

.pyc 文件什么时候失效

Python 不依赖文件修改时间做简单比对，而是通过「源码文件的最后修改时间 + 大小」与 .pyc 头部存储的值比对。一旦不匹配，就判定为过期，丢弃旧 .pyc 并重建。

• 修改 .py 文件内容后，下次 import 必然触发重编译
• 用 touch 仅更新时间戳、或用编辑器保存空修改，也会导致校验失败
• 跨平台复制 .pyc 通常失效：不同系统下文件大小/时间精度可能不同；更关键的是，.pyc 头部硬编码了 Python 版本和 ABI 标签（如 cpython-311），版本不一致直接拒绝加载
• 使用 compileall 手动生成时，若指定 -f 强制覆盖，或 -l 不递归子包，容易遗漏部分模块，造成混合新旧缓存

如何控制 .pyc 的生成行为

有多个层级可干预，优先级从高到低：启动参数 > 环境变量 > 运行时设置。

• 启动时加 -B：完全禁止生成 .pyc（包括 __pycache__）
• 设环境变量 PYTHONPYCACHEPREFIX=/tmp/pycache：把所有缓存统一移到外部路径，避免污染项目目录（Python 3.8+）
• 设 PYTHONNOUSERSITE=1 不影响 .pyc，但设 PYTHONDONTWRITEBYTECODE=1 效果等同于 -B
• 运行时调用 sys.dont_write_bytecode = True 可动态关闭当前解释器实例的写入，但无法影响已导入模块的缓存行为
• 注意：py_compile.compile() 和 compileall.compile_dir() 仍会生成，它们绕过解释器的自动机制

调试 .pyc 相关问题的实用技巧

当遇到 ImportError、奇怪的 ModuleNotFoundError，或怀疑缓存污染时，别急着删整个 __pycache__ —— 先确认是否真由 .pyc 引起。