Python .pyc 文件的生成规则与失效机制

python首次导入模块时自动在__pycache__目录生成.pyc文件，文件名含版本标识；直接运行脚本不生成，除非加-b等选项或设环境变量；.pyc通过源文件mtime或哈希值判断是否过期。

Python 怎么自动生成 .pyc 文件

Python 在首次导入模块时，会自动编译源码生成 .pyc 文件，存放在 __pycache__ 目录下，文件名包含 Python 版本标识（如 module.cpython-311.pyc）。这个过程由解释器内部触发，不需要手动调用 compile() 或 py_compile 模块——除非你明确想预编译。

• 仅对被 import 的模块生效；直接运行的脚本（python script.py）默认不生成 .pyc，除非加 -B 以外的选项或设置环境变量
• .pyc 不会在源文件被 exec()、eval() 或 importlib.util.spec_from_file_location() 手动加载时自动生成
• 如果当前目录不可写（比如只读文件系统），.pyc 生成失败但不会报错，只是跳过缓存

.pyc 文件什么时候失效

Python 通过比对源文件的最后修改时间（mtime）和 .pyc 头部嵌入的时间戳来判断是否过期。只要源文件被修改，下次 import 就会重新生成。

• 修改时间精度依赖系统：windows FAT32 只保留 2 秒粒度，可能导致“改了但没重编译”
• 如果用 touch 回拨源文件时间戳到早于 .pyc，Python 会误判为未改动，继续用旧缓存（常见于 CI/CD 中从镜像复制文件后时间错乱）
• Python 3.7+ 引入了基于哈希的验证（check_source=True 默认开启），但仅当 .pyc 是用哈希模式生成时才生效；普通场景仍靠 mtime

怎么强制禁用或控制 .pyc 生成

有三个互斥层级：启动参数 > 环境变量 > 运行时设置。优先级从高到低。

• 启动时加 -B：完全禁止写 .pyc（包括 __pycache__ 和旧式同目录 .pyc）
• 设环境变量 PYTHONDONTWRITEBYTECODE=1：效果等同 -B，适合容器或部署脚本统一控制
• 运行中调用 sys.dont_write_bytecode = True：只影响后续 import，对已导入模块无效；且不能恢复（Python 不提供“重新开启”API）
• 注意：-B 不影响已存在的 .pyc 加载——它只阻止新生成，旧缓存仍会被读取

为什么删了 __pycache__ 还是报错说找不到 .pyc

不会报这个错。Python 从不因缺失 .pyc 报错；它只在源码不存在、语法错误、或 .pyc 格式损坏（比如用不同版本 Python 生成后又换版本运行）时出问题。

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

• 典型误判场景：把 .pyc 单独拷贝到无源码的环境运行，但目标机器 Python 版本不匹配（如 3.11 生成的 .pyc 放到 3.10 下执行），会抛 ImportError: bad magic number
• .pyc 文件权限不对（如无读权限）会导致 PermissionError，而非“找不到”
• 路径问题常被误认为缓存问题：比如 sys.path 里没有当前目录，即使有 .pyc 也根本不会被扫描到

真正容易被忽略的是：Python 缓存验证逻辑不校验源码内容是否一致，只认时间戳或哈希值；而哈希值默认只在显式启用（py_compile.compile(..., invalidation_mode=...)）时才写入。这意味着，靠时间戳判断的机制，在 NFS、容器挂载、git 清理等场景下极易失效。