很多 Python 初学者都会遇到同一个困惑自己明明只是写了一个.py文件跑完一遍之后项目里却莫名其妙多了个__pycache__文件夹里面躺着几个.pyc文件。有人直接动手删除觉得这是“系统垃圾”也有人上网搜了半天只得到一句“别删删了也会自动再生成”。但真正能讲清楚.pyc是什么、为什么存在、由谁生成、能被怎么用起来的资料其实并不多。这篇文章我就从“编译中间态”这个角度把.pyc从头到尾拆一遍。你会看到 Python 是怎么把源码变成字节码、又是怎么用.pyc缓存这些字节码的也会看到实际项目中怎么主动生成和管理.pyc、怎么排查“改完代码不生效”这类经典问题。无论你是刚入门的新手还是已经在写工程项目的开发者只要你在用 Python理解这一层机制都会很有帮助。1. 认识 .pycPython 的“编译中间态”到底是什么1.1 一个常见的场景__pycache__ 从哪来的先还原一个最典型的现场。你写了一个demo.pydef hello(): print(hello, pyc) if __name__ __main__: hello()当你执行python demo.py后项目目录下会出现一个__pycache__文件夹里面多了一个类似demo.cpython-312.pyc的文件。如果你再执行python demo.py第二次这个文件不会重新生成而是会被直接使用。注意一个细节直接运行python demo.py这种顶层脚本时Python 其实也会顺便把脚本编译进缓存但与标准模块机制相比路径判断会有些差异。正常情况下大部分.pyc都是在你import某个模块时生成的而不是在你要import的入口文件本身生成。这一点很关键它决定了.pyc的缓存逻辑本质上服务于模块加载机制。__pycache__目录从 Python 3.2 开始正式引入它解决了很多历史问题。在 Python 2 时代foo.py编译后会在源文件旁边生成一个foo.pyc直接把源码目录弄得乱七八糟。Python 3.2 之后就统一放进了__pycache__并且在文件名里带上了解释器版本信息不同版本的缓存可以共存互不干扰。这也是为什么你会看到demo.cpython-312.pyc这种带着cpython-312前缀的文件名。1.2 编译中间态从 .py 到字节码再到 pyc很多教程喜欢把 Python 称为“解释型语言”这个说法其实只对了一半。Python 确实不需要像 C/C 那样先编译成机器码再运行但它也不是一行一行直接“翻译”执行的。准确地说Python 内部会先把源码编译成一种平台无关的中间表示——字节码bytecode再由解释器逐个执行这些字节码指令。整个流程大致是源码.py先经过词法分析拆成一个个 token。token 流再经过语法分析生成抽象语法树AST。AST 被编译成 code object每个 code object 里保存着字节码指令、常量表、变量名表等信息。code object 被序列化后写入.pyc文件方便下次加载时跳过前面的编译步骤。解释器读取 code object 里的字节码在一个基于栈的虚拟机里逐条执行。所以.pyc里保存的并不是机器码而是字节码也就是第 3 步产出的“编译中间态”。它和 Java 的.class文件有相似之处但 Java 的字节码主要为了跨平台运行Python 的字节码则更强调“跨源码复用”只要源码没变就没必要重新编译一遍。字节码长什么样你可以随手验证一下import dis dis.dis(x 1 2)输出大概是0 LOAD_CONST 0 (1) 2 LOAD_CONST 1 (2) 4 BINARY_OP 0 () 6 STORE_NAME 0 (x) 8 LOAD_CONST 2 (None) 10 RETURN_VALUELOAD_CONST、STORE_NAME这类助记符就是解释器能识别的字节码指令。Python 解释器本质上就是一个循环从 code object 里取指令、执行指令、更新栈状态。.pyc缓存的目标就是省掉从源码到字节码这一段需要做大量解析和编译工作的过程。1.3 pyc 解决的三个核心问题为什么要费这么大劲引入.pyc和__pycache__主要解决三个问题。第一启动速度。当一个大型项目被import时比如你写了一个import requests里面会连带加载几十上百个模块。如果每次启动都把全部源码重新编译一遍那每次冷启动都会浪费大量时间。.pyc相当于预编译结果加载时只需要读文件、反序列化比重新编译快得多。第二版本兼容。同一个项目目录可能今天用 Python 3.11 跑明天用 Python 3.12 跑。如果缓存文件单独放在源目录旁边两个版本的解释器就会互相覆盖。__pycache__里带版本标签的文件名让不同解释器可以各自保留自己的缓存井水不犯河水。第三编译结果校验。源码文件有改动时Python 需要能察觉到“缓存过期了”从而触发重新编译。.pyc文件头保存了源码文件的修改时间、文件大小甚至内容哈希解释器就是靠这些信息判断缓存是否仍然有效。但这里有个有趣的事实.pyc不能提升 Python 的运行速度它只提升加载速度。解释器拿到字节码之后照样是逐条解释执行并不会因为指令来自.pyc就飞起来。很多人误以为“用 pyc 运行更快”其实那是把“加载更快”和“运行更快”搞混了。2. 深入拆解 __pycache__命名规则与校验逻辑2.1 文件名的暗号cpython-312 与 opt 标记你见过demo.cpython-312.pyc也见过demo.cpython-312.opt-1.pyc、demo.cpython-312.opt-2.pyc这些文件名并不是随便取的它们是按照一套规则拼出来的模块名 解释器标签 优化级别标记 .pyc后缀。解释器标签部分直接对应了sys.implementation.cache_tag。你可以在解释器里运行import sys print(sys.implementation.cache_tag)CPython 3.12 环境下输出就是cpython-312。换成 PyPy 或其他 Python 实现这个标签会不一样所以同一个项目目录下即使混用不同的 Python 实现缓存文件也不会撞车。优化级别标记则对应 Python 启动时的-O和-OO参数标记对应的启动参数行为差异无默认启动__debug__为Trueassert语句正常生效opt-1python -O__debug__变为Falseassert语句会被移除opt-2python -OO在-O基础上还会移除文档字符串也就是说同一个demo.py可能会在__pycache__里同时产生demo.cpython-312.pyc和demo.cpython-312.opt-1.pyc两份缓存分别给正常模式和优化模式用。当你启动时带了-OPython 就去挑对应优化的那一份。有人会问既然-OO能移除assert和 docstring那是不是可以强制生成指定优化级别的缓存可以后面我会讲到compileall和py_compile的具体用法。2.2 magic number、时间戳、源码哈希pyc 的“有效期”判断一个.pyc文件能不能被当前解释器加载首先要看文件头里的 magic number。magic number 是解释器在生成字节码时按 Python 版本算出的一个标识。CPython 每个版本都可能变动它保证了不同版本的字节码不会被混着加载。如果 magic number 对不上解释器会直接忽略这个.pyc重新编译源码甚至报错提示“bad magic number”。过了 magic number 这一关接下来才是真正判断缓存是否过期。CPython 提供了两种失效校验模式时间戳模式文件头保存源码文件的mtime修改时间和size文件大小。加载时对比源码文件的当前mtime、size如果一致就认为缓存有效。哈希模式文件头保存源码文件内容的哈希摘要。即使文件时间戳被改动、内容没变也不会误判过期反过来如果内容真的变了哈希一定对不上缓存就会失效。哈希模式由 PEP 552 引入你可以通过py_compile手动生成这样带哈希校验的.pyc。这种模式在源码版本管理场景下尤其有用。因为我实际遇到过一种情况用 git 切换分支后源码文件的内容确实变了但由于文件系统时间戳可能被设置成“不变”甚至倒退Python 默认的时间戳模式会误以为源码没变继续加载旧缓存导致奇怪的“改了代码却不生效”的问题。哈希模式能很好地规避这个坑。2.3 为什么不同 Python 版本的 pyc 不能混用字节码本身是平台无关的但和 Python 版本强相关。CPython 3.11 的字节码和 3.12 的字节码在指令编号、参数格式上都有调整。你把 Python 3.12 环境下生成的.pyc复制到 Python 3.11 环境里大概率没法用即使勉强加载成功也可能因为字节码指令语义不一致而执行出错。所以.pyc的兼容边界是同一个 Python 大版本、同一个实现、同一个优化级别。跨平台拷贝.pyc一般没问题因为字节码不涉及具体 CPU 指令。但跨版本、跨实现CPython 和 PyPy就不行了这也是为什么__pycache__命名里要刻意区分解释器标签。理解这一点后你就该明白.pyc不能当作一个通用的“预编译产物”到处分发它紧紧绑定在生成它的解释器身上。如果你想分发“不需要源码”的模块除了.pyc还要同时明确目标解释器版本否则很容易踩兼容性的大坑。3. 实操演练手工生成、加载和“解剖”pyc 文件3.1 用 py_compile 手工编译一个文件正常情况下.pyc由解释器在 import 时自动生成但如果你需要提前编译、或需要控制缓存生成的位置可以用标准库py_compile。我先创建一个demo.pydef add(a, b): return a b def say(): print(hello from pyc)然后执行python -m py_compile demo.pydemo.py对应的.pyc就会出现在__pycache__里。如果想指定输出文件名可以用cfile参数import py_compile py_compile.compile( demo.py, cfilemy_demo.pyc, doraiseTrue, )这里的doraiseTrue表示编译出错时直接抛出异常而不是只在终端打印一行错误信息这在脚本化、自动化场景下非常有用。py_compile还有一个值得关注的参数invalidation_mode可以选择时间戳模式还是哈希模式。比如我想生成一个基于源码内容哈希校验的.pycimport py_compile py_compile.compile( demo.py, invalidation_modepy_compile.PycInvalidationMode.CHECKED_HASH, )生成的.pyc会带上哈希头后续加载时即使mtime没变只要源码内容变了缓存也会失效。在源码版本管理复杂的项目里手工用这种模式编译一次能解决不少诡异缓存问题。注意一点py_compile.compile默认返回编译后的文件路径但你千万别以为它只编译不加载。它只是写了缓存文件不会把模块导入当前进程。要加载生成的.pyc还要看后面的 import 机制。3.2 用 compileall 批量预编译整个项目单个文件可以用py_compile整个项目就要用compileall。比如你有一个待部署的项目目录myproject想一次性把里面所有.py都编译成.pycpython -m compileall myproject/默认会在每个子目录下生成对应的__pycache__。如果你想要“旧式布局”把.pyc直接放在源文件旁边可以加-bpython -m compileall -b myproject/批量编译在很多场景下很实用。比如离线部署时你想让目标机器首次启动快一点或者你压根不想把源代码直接放在服务器上就可以在构建机上先compileall然后只拷贝编译出来的.pyc文件过去。compileall还有几个参数我实际用下来比较顺手-f强制重新编译忽略已有缓存。-q静默模式不打印每个编译成功的文件。-o/-i控制输出路径和包含目录适合在大型项目里按需编译。一个比较常见的 CI 场景是在构建阶段跑一次python -m compileall -q -f -b .确保所有源码在发布前都能通过编译同时把所有.pyc放到源码旁边然后按需打包。这样既能提前暴露语法问题又能给部署机备好缓存。3.3 不靠 import 直接加载 pyc 的三种方式很多教程讲了半天.pyc怎么生成却很少讲怎么直接加载一个.pyc。在实际工作中你会遇到“只有.pyc文件没有.py源码”的场景。这时有几个加载思路。第一种用标准库importlib。假设当前目录下有一个demo.cpython-312.pyc模块名是demo直接这样写import importlib.util spec importlib.util.spec_from_file_location( demo, demo.cpython-312.pyc, ) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) print(module.add(1, 2))但这里有个现实问题如果目录下没有对应的.py源文件Python 在某些版本下使用sourceless逻辑时loader.get_source()可能会抛ImportError: source code cannot be found之类的异常导致importlib.util.spec_from_file_location这条路不稳定。第二种使用importlib.machinery.SourcelessFileLoaderfrom importlib.machinery import SourcelessFileLoader loader SourcelessFileLoader(demo, demo.cpython-312.pyc) module loader.load_module(demo)但load_module在 Python 3.12 里已经被标记为废弃新代码不建议依赖它。第三种最粗暴也最可控直接用marshal解析.pyc文件里的 code object然后手动创建模块。因为.pyc本身就是 code object 的序列化结果import marshal import types def load_pyc_standalone(path: str, module_name: str) - types.ModuleType: with open(path, rb) as f: f.read(16) # 跳过 pyc 文件头 code marshal.load(f) module types.ModuleType(module_name) module.__file__ path exec(code, module.__dict__) return module mod load_pyc_standalone(demo.cpython-312.pyc, demo) print(mod.add(2, 3))这段代码能跑通是因为.pyc里的核心内容就是marshal序列化后的 code object。跳过文件头之后marshal.load直接还原出一个 code object再把它exec到新模块的命名空间里就等价于完成了一次模块加载。注意marshal本身是一个不安全的格式不要加载任何来路不明的.pyc或.pyzm数据。它能执行任意代码等于给恶意文件开了一扇大门。3.4 用 dis 模块查看字节码理解“中间态”长什么样想真正理解.pyc里装的是什么最好直接看字节码。用标准库dis就能做到import dis dis.dis(def f(x): return x 1)输出类似0 RESUME 0 2 LOAD_CONST 0 (code object f at ...) 4 MAKE_FUNCTION 0 6 STORE_NAME 0 (f) 8 LOAD_CONST 1 (None) 10 RETURN_VALUE Disassembly of code object f at ...: 0 RESUME 0 2 LOAD_FAST 0 (x) 4 LOAD_CONST 1 (1) 6 BINARY_OP 0 () 10 RETURN_VALUE每个嵌套的函数、类、lambda都有自己的 code object形成一棵树。你之前加载的.pyc本质上就是这棵 code object 树的根。如果你想直接反汇编一个.pyc文件也可以先手动加载 code object再交给dispython -m dis demo.pyc某些版本下直接指定.pyc文件反汇编是可行的。如果遇到格式问题可以先用前面的marshal加载方法取出 code object再调用dis.dis(code)效果一样。理解字节码还有一个好处当你怀疑“代码明明改了却没生效”时可以直接反汇编加载到的模块看看它执行的到底是不是你预期的那份代码比起瞎猜缓存问题要直观得多。4. 真实场景里的 pyc分发、打包与性能4.1 用 pyc 做“源码保护”到底靠不靠谱很多人第一次接触.pyc都会冒出一个念头我把.py文件删掉只发布.pyc是不是就能保护自己的源码了思路本身能理解但现实很骨感。.pyc只是把源码编译成了字节码它并不加密。只要别人拿到.pyc完全可以用反编译工具还原出接近源码的东西。Python 3.8 及以下的字节码有uncompyle6、decompyle3这类工具能直接还原出可读性很高的源码。Python 3.9 到 3.11 也有不少社区工具能还原大部分结构虽然不完美但足以把核心逻辑暴露无遗。到了 Python 3.12字节码变化更大成熟的反编译工具跟进得慢但这不代表.pyc就是安全的。它只是“暂时难还原”并不等于“无法还原”。真正的源码保护应该考虑 Cython 编译成 C 扩展模块、用 Nuitka 把 Python 转成 C 再编译或者用商业混淆工具。这些方案会显著增加逆向成本但也不是绝对不可逆。所以我的建议很简单不要把.pyc当作加密手段。它适合做“减少源码暴露面”的临时措施但不适合承载真正的核心机密。4.2 离线部署无源码模块把 pyc 当作依赖的一部分虽然没有加密强度但.pyc在离线部署场景里还是很有用。比如你的交付物是一个 Python 命令行工具对方环境里没有你的源码你也不想把完整的.py结构暴露给客户那么可以在构建机上python -m compileall -b package_dir/然后把package_dir下的所有.pyc打包交付给对方。对方只要 Python 版本和构建时一致就能正常import使用。这个方案要注意几点目标机器必须使用和构建时相同的 Python 实现和版本否则 magic number 不对加载直接失败。有些框架比如 Django、Flask会在启动时扫描模板、配置文件这些文件不属于.pyc管的范围依然要一并分发。如果源码里有依赖路径、动态导入__import__、importlib.import_module的逻辑只发.pyc可能遇到找不到模块的问题需要在交付前做一轮完整的启动测试。比起发源码这种方式至少让对方不能直接双击打开.py文件看逻辑能挡住一小部分人。4.3 从 pyc 到 exePyInstaller 内部发生了什么很多人用过pyinstaller把 Python 脚本打包成.exe却不知道打包过程其实绕了一个圈PyInstaller 会先把你的.py源码编译成.pyc再把这些.pyc连同依赖库一起压进归档文件。具体来说PyInstaller 生成的可执行文件里有一个名为PYZ-00.pyz的归档里面就是一堆压缩过的.pyc。启动时PyInstaller 会通过自己实现的 import 钩子从归档里解压出.pyc并加载到解释器执行。这就带来一个很多人忽略的事实用 PyInstaller 打包出来的程序并不能真正保护源码。发布后的二进制里依然可以提取出.pyc再经过反编译还原出接近源码的内容。这也再次说明了不要把“打包成 exe”和“源码加密”画等号。但理解.pyc在 PyInstaller 里的角色对你排查打包问题很有帮助。比如你遇到“打包后运行报错提示 module not found”一个常见原因是某些模块是动态导入的PyInstaller 在静态分析 import 语句时没收集到对应的.pyc。这时候你不是去看代码逻辑而是要检查打包配置里的 hidden imports把缺失模块的名字手工加进去。4.4 性能优化预编译到底有没有用回到性能问题。.pyc能优化的是启动阶段而不是运行阶段。真实感受大概是如果一个大型项目需要 import 几百个模块第一次运行因为要逐个编译源码可能花 3 秒第二次运行直接读.pyc降到 1.5 秒。第二次的节省对于反复启动 CLI 工具、频繁重启服务的场景体感非常明显。如果你想让这个过程更可控可以在构建阶段就把整个项目的缓存准备好python -m compileall -q -f .这样第一批用户启动时就不用经历“编译编译再编译”的冷启动阶段了。但要注意compileall只对标准库和纯 Python 模块有效C 扩展模块.so/.pyd本来就是编译后的二进制不经过.pyc这一步。如果项目启动还是慢就不要盯着.pyc死磕了可以用python -X importtime看每个模块的 import 耗时找出到底是谁拖慢了启动这比盲目预编译更有针对性。5. 常见问题与排查技巧实录5.1 改了源码为什么运行结果还是旧的这应该是.pyc相关最经典的问题了。代码明明改了print也加上了为什么跑出来的结果还是老逻辑最可能的原因是缓存失效判断出了问题。Python 默认用时间戳模式判断缓存是否有效如果.pyc的“来源源码 mtime”大于等于当前.py的 mtime就认为缓存新鲜直接加载。但当你用 git、svn 切换版本或者同步工具把文件时间戳改乱时.py的 mtime 可能比.pyc里记录的还小Python 就误以为源码没变继续用旧缓存。排查思路很简单查看.py和对应.pyc的修改时间确认谁更“新”。删除对应模块的__pycache__重新运行。如果经常出现这个问题建议改用哈希校验的缓存。处理命令也很直接find . -type d -name __pycache__ -exec rm -rf {} 删完之后再跑一次让 Python 重新编译源码正常都能恢复。另外不要忽略sys.path的混乱如果环境里有多个同名模块比如某个虚拟环境里也装了一份相同模块解释器可能加载了另一个版本的.pyc。这时候要用print(module.__file__)确认实际加载路径。5.2 __pycache__ 越来越多能安全删除吗答案是能。.pyc本身只是缓存删掉后 Python 会在下次 import 时重新生成。它不像某些程序的数据文件删了会导致状态丢失。但要注意如果你是在一个大型项目里删除所有__pycache__后第一个用户访问时会有一次明显的“编译冷启动”可能要等上一会儿。所以删除缓存这个动作更适合放在版本切换、部署更新的时机而不是在用户使用高峰时手动清理。如果项目长期运行__pycache__里可能会有大量旧版本、旧优化级别的缓存文件堆积时间久了确实占空间。可以写一个定时清理脚本find . -type d -name __pycache__ -exec rm -rf {} 也可以只清理超过多少天的缓存find . -type d -name __pycache__ -mtime 30 -exec rm -rf {} 这些操作不会影响业务逻辑但执行后第一次访问需要重新编译务必安排在低峰期。5.3 如何彻底关闭 pyc 生成有些场景就是不想让 Python 生成.pyc比如你的项目运行在只读文件系统上或者你希望源码目录保持绝对干净。最常用的方式是设置环境变量export PYTHONDONTWRITEBYTECODE1也可以在启动命令时加参数python -B app.py还可以在代码里强制设置import sys sys.dont_write_bytecode True需要注意的是sys.dont_write_bytecode True必须在任何模块 import 之前设置才有效否则已经触发的编译动作不会回退。关闭.pyc生成并不意味着解释器不编译源码了它只是不把编译结果写入磁盘。运行期的import照样会编译只是每次都要重新编译等于放弃了缓存带来的启动加速。在只读环境里这是没办法的办法但在普通机器上我不建议长期关闭因为代价是启动变慢。5.4 把缓存集中到一个目录PYTHONPYCACHEPREFIX有些团队很在意源码目录的整洁或者部署环境要求程序只能写特定目录。这时可以用PYTHONPYCACHEPREFIX环境变量把__pycache__统一指到一个地方export PYTHONPYCACHEPREFIX/tmp/pycache python app.py启动时所有模块的.pyc都会写到/tmp/pycache下而不是散落在源码目录各处。这个功能也对应一个启动参数python -X pycache_prefix/tmp/pycache app.py这个方案在 CI 构建、容器化部署里很好用。比如在 Docker 构建阶段把缓存写到/tmp既不影响源码目录、又能避免将__pycache__带进镜像。要注意的是PYTHONPYCACHEPREFIX不会改变缓存文件的命名规则只是改变缓存文件存放的根目录位置。5.5 问题排查速查表现象可能原因建议处理改完代码还是旧逻辑时间戳模式下缓存误判有效删除__pycache__改用哈希校验缓存切换 git 分支后报错.pyc缓存与当前源码不匹配清理缓存后重新运行复制.pyc到另一台机器无法加载Python 版本不一致magic number 不匹配在目标机器上重新编译生成运行瞬间出现大量__pycache__多模块首次 import 自动缓存如不需要可设置PYTHONDONTWRITEBYTECODE只读文件系统报写入错误解释器无法写入缓存加-B参数或设置环境变量模块加载了不是同一个来源的代码sys.path路径顺序问题打印module.__file__确认来源打包后缺少模块PyInstaller 未收集动态导入模块在 spec 文件中补充 hidden imports6. 最后的个人经验与扩展建议6.1 我对 pyc 的态度了解机制别迷信“加速”跑过这么多年 Python 项目后我的体会是.pyc是一个“自动挡”机制绝大多数情况下你不用主动碰它但你要理解它背后的规则。很多人遇到“改了代码没生效”第一反应是删掉整个虚拟环境重装依赖最后发现只是__pycache__里的一份旧缓存作祟折腾半天纯属浪费时间。还有一点.pyc并不能帮你把 Python 程序变快它只优化加载路径。如果真觉得项目启动慢先分析 import 时间再说预编译的事。我最常干的操作是加一个-X importtime看看到底是哪个模块吃了启动时间而不是盲目批量预编译。6.2 真正值得深入的方向理解.pyc之后往上走会更顺。比如你可以去看看 PEP 3147 和 PEP 552这两篇规范把__pycache__目录设计、缓存失效策略讲得很系统。再往深一点可以研究 Cython、Nuitka 这类工具它们输出的已经不是 Python 字节码而是 C 代码甚至机器码这是“更靠后”的编译产物也是很多商业项目保护源码的手段。如果你想在 Python 这条路上走得更扎实我建议你亲手做一次实验写一个一百行左右的模块用py_compile生成.pyc再用marshal加载出来最后用dis反汇编从头到尾看一遍自己代码的字节码长什么样。这个过程比你背十遍“Python 是先编译后解释”都来得有效。等你真正看清.pyc里装的是什么很多相关的问题就不再神秘了。