1. 从一次打包翻车说起OSError 是怎么冒出来的Windows 上用 PyInstaller 打包 Python 脚本本来是个挺顺手的活儿——一条命令下去dist 目录里躺着一个 exe双击就能跑发给同事或者丢到没有 Python 环境的机器上也能用。但偏偏有那么一类报错会在你打包完成、满心欢喜双击 exe 的那一刻给你当头一棒OSError: could not get source code这个报错最让人抓狂的地方在于在 PyCharm 或者命令行里直接python main.py跑得好好的一打包就炸。你甚至不知道它是打包阶段出的问题还是运行阶段出的问题因为 PyInstaller 打包时可能一声不吭直到 exe 启动才把异常抛出来。我前后在几个项目里都撞上过这个坑涉及的场景包括用了inspect.getsource()做动态分析的脚本、用了dill或cloudpickle做序列化的任务、以及一些依赖inspect.stack()做日志追踪的框架。每次排查路径都不太一样但根因其实高度收敛。这篇就把我踩过的坑、排查链路和最终稳定的解决方案完整梳理一遍尽量让你少走弯路。先说清楚这个报错到底在说什么。could not get source code是 Python 标准库inspect模块抛出来的准确地说是inspect.getsource()、inspect.getsourcelines()、inspect.findsource()这一族函数在拿不到对象的源码文本时抛出的OSError。注意它抛的是OSError而不是ImportError或AttributeError这一点很关键——它意味着 Python 认为这个对象应该有源码但去取的时候取不到。那为什么打包之后就取不到了因为 PyInstaller 打包的本质是把你的.py源文件编译成字节码塞进一个压缩归档里运行时由一个内置的引导程序解压加载。也就是说exe 运行的时候磁盘上根本没有.py源文件。inspect.getsource()的工作方式是先通过对象的__code__.co_filename找到对应的文件路径然后打开这个文件读取源码行。文件都不存在了自然就could not get source code。理解了这个机制后面所有的解决方案就都有了统一的解释框架要么让源码在运行时能被找到要么让代码根本不依赖源码。下面我按先定位、再分类、后解决的顺序展开。2. 先别急着改代码三步定位到底是哪一行触发的很多人一看到这个报错就开始瞎改加--hidden-import、换打包参数、甚至重装 PyInstaller结果越改越乱。正确的做法是先精确定位到是哪一行代码、哪个库、在什么时机触发了这个异常。我总结了一个三步定位法实测非常有效。2.1 第一步让 exe 把完整堆栈吐出来PyInstaller 打包时如果用了--windowed也就是-w参数程序是没有控制台的异常会被吞掉或者只弹一个模糊的错误框。排查阶段一定要先用带控制台的方式打包pyinstaller --onefile --console main.py然后在命令行里运行生成的 exe让完整的 traceback 打印出来。你会看到类似这样的堆栈Traceback (most recent call last): File main.py, line 42, in module File some_lib\core.py, line 118, in build File inspect.py, line 1024, in getsource File inspect.py, line 987, in getsourcelines File inspect.py, line 826, in findsource OSError: could not get source code关键信息是倒数第二三行的调用来源——是some_lib\core.py里的某一行调用了inspect.getsource。这一步能帮你锁定是我自己的代码调用的还是某个第三方库内部调用的。2.2 第二步区分打包期报错还是运行期报错这里有个容易混淆的点。有些情况下报错发生在PyInstaller 分析依赖的阶段而不是 exe 运行阶段。典型特征是打包命令执行到一半就中断控制台直接抛出OSError: could not get source code。这种情况通常是因为某个库在导入时模块顶层就调用了inspect.getsource比如某些做自动注册、自动文档生成的库。PyInstaller 在分析 import 链时会真正 import 这些模块于是触发异常。区分方法很简单如果报错出现在pyinstaller xxx.py命令的输出里且打包没生成 exe →打包期报错如果 exe 生成成功双击或命令行运行才报错 →运行期报错两者的解决思路不同打包期报错往往需要--exclude-module排除掉那个惹事的库或者用 hook 干预运行期报错则主要靠补源码或改调用方式。2.3 第三步用最小复现脚本验证假设定位到可疑库之后别急着在完整项目里改。写一个最小脚本import inspect def foo(): return 1 print(inspect.getsource(foo))先用python min_test.py跑确认正常输出。然后pyinstaller --onefile --console min_test.py打包再跑。如果这个最小脚本也报could not get source code那你就有了一个干净的复现环境可以在这个环境里快速试验各种解决方案不用每次都在大项目里折腾几分钟。我个人的经验是90% 的这类问题都能在最小复现脚本里复现剩下 10% 是特定库的特定版本行为需要单独处理。3. 根因分类四种典型触发场景与对应特征定位到具体位置之后接下来要判断它属于哪一类。我把这些年遇到的场景归成四类每一类的特征和解决方向都不一样。3.1 场景一自己的代码显式调用了 inspect.getsource这是最直接的一类。比如你写了个装饰器想自动生成文档字符串import inspect def auto_doc(func): func.__doc__ inspect.getsource(func) return func或者写了个插件系统通过inspect.getsource读取插件源码做校验。这类场景的特征是堆栈里能直接看到你自己的文件名。解决方向有两个一是改调用方式用func.__doc__、func.__code__.co_consts等不依赖源码的替代方案二是补源码把源文件一起打包进去后面第 4 节详述。3.2 场景二第三方库内部依赖源码这类最隐蔽因为报错堆栈里全是第三方库的文件名你甚至不知道它为什么要读源码。常见的重灾区包括序列化库dill、cloudpickle在序列化函数或类时会尝试读取源码来重建对象尤其是序列化 lambda、闭包、动态定义的类时。依赖注入/自动装配框架某些框架通过inspect.getsource分析函数签名和默认值。日志/追踪库为了打印调用位置会读取调用栈对应文件的源码行。测试框架pytest的某些插件在收集测试时会读源码。ORM 和 schema 库部分库通过源码分析来推断字段类型。判断方法看堆栈里inspect.py上面那一层是哪个库的文件。如果是dill\_dill.py那就是序列化问题如果是某个框架的core.py就去查那个框架的文档看有没有禁用源码分析的开关。3.3 场景三动态生成的代码对象有一类情况比较特殊代码本身就是运行时动态生成的比如用exec()、compile()或者types.FunctionType创建的函数。这类对象压根就没有对应的源文件co_filename可能是string或者一个不存在的路径。code compile(def dynamic(): return 42, dynamic, exec) namespace {} exec(code, namespace) dynamic_func namespace[dynamic] import inspect inspect.getsource(dynamic_func) # 必然报错因为 dynamic 不是真实文件这种场景下补源码是没用的因为本来就没有源码。唯一的出路是改调用方式或者给动态函数手动设置__doc__和元信息。3.4 场景四PyInstaller 的路径映射导致的假性找不到最后一类比较微妙。有时候源码文件确实被打包进去了比如你用--add-data加了.py文件但inspect还是找不到。原因是 PyInstaller 运行时会把资源解压到一个临时目录sys._MEIPASS而co_filename里记录的路径是打包前的原始路径两者对不上。这类场景的特征是你能在sys._MEIPASS目录下找到那个.py文件但inspect就是读不到。解决方法是做路径重映射把co_filename里的原始路径映射到_MEIPASS下的实际路径。这个后面第 5 节会给具体代码。为了让你快速对号入座我把四类场景整理成一张对照表场景堆栈特征是否有源码文件推荐方向自己调用 getsource堆栈含自己的文件名有改调用方式或补源码第三方库内部调用堆栈含库文件名有查库开关或补源码动态生成代码co_filename 为string等无只能改调用方式路径映射错位文件在 _MEIPASS 但读不到有位置不同路径重映射4. 补源码方案把 .py 文件塞进 exe 的正确姿势如果你的场景属于有源码但打包后找不到那么补源码是最直接的解法。核心思路是让.py文件在运行时能被inspect找到。具体有几种做法各有取舍。4.1 用 --add-data 把源码目录一起打包PyInstaller 的--add-data参数可以把任意文件或目录打包进 exe。Windows 下的语法是源路径;目标路径注意是分号Linux/macOS 是冒号pyinstaller --onefile --console --add-data src;src main.py这条命令会把项目里的src目录整个打包进去运行时解压到sys._MEIPASS/src。但这里有个坑inspect找的是co_filename里的原始路径而不是_MEIPASS下的路径。所以光加--add-data往往不够还需要配合路径重映射。4.2 运行时做路径重映射在程序入口的最前面main.py的顶部任何业务 import 之前加上这段代码import sys import os if getattr(sys, frozen, False): # 运行在 PyInstaller 打包的 exe 中 base sys._MEIPASS # 把原始源码路径映射到 _MEIPASS 下 # 假设打包时源码在 src 目录原始路径形如 .../project/src/xxx.py # 这里根据你的实际目录结构调整 def _remap(path): if not path or not path.endswith(.py): return path # 提取 src 之后的相对路径 marker os.sep src os.sep idx path.find(marker) if idx -1: return path rel path[idx len(marker):] candidate os.path.join(base, src, rel) return candidate if os.path.exists(candidate) else path # 关键inspect 内部用的是 linecache重定向 linecache 的读取 import linecache _orig_getlines linecache.getlines def _patched_getlines(filename, module_globalsNone): return _orig_getlines(_remap(filename), module_globals) linecache.getlines _patched_getlines这段代码的原理是inspect.getsource最终是通过linecache.getlines(filename)读取文件内容的。我们拦截linecache.getlines把原始路径替换成_MEIPASS下的实际路径inspect就能正常读到源码了。注意这段代码必须在任何可能触发inspect.getsource的 import 之前执行。如果某个库在 import 时就调用了inspect而你的重映射代码写在 import 之后那就来不及了。所以放在main.py最顶部是最稳妥的。4.3 用 sys.path 和file的配合技巧还有一种更土但有时更有效的办法把源码目录直接加到sys.path并确保co_filename能被解析。具体做法是在打包时用--paths指定源码目录运行时再手动把_MEIPASS加到sys.pathimport sys import os if getattr(sys, frozen, False): sys.path.insert(0, os.path.join(sys._MEIPASS, src))但说实话这个办法对inspect.getsource帮助有限因为inspect不查sys.path它只认co_filename。所以它更适合解决import 找不到模块的问题而不是getsource 找不到源码的问题。别把这两个问题搞混了。4.4 补源码方案的代价与取舍补源码不是没有代价的。最直接的影响是exe 体积变大——源码文件本身不大但如果你的项目源码有几百个文件加上--add-data后 exe 可能膨胀几 MB 到几十 MB。其次源码暴露了任何拿到 exe 的人都能在临时目录里翻到你的.py文件。如果你的代码有商业机密这一点必须权衡。我的建议是只补真正需要被 inspect 读取的那部分源码而不是整个项目。比如只有plugins目录下的插件需要被读取那就只--add-data plugins;plugins别把整个src都塞进去。5. 改调用方式从根上绕开 getsource 的几种替代方案如果你的场景属于动态生成代码或者补源码代价太大那么改调用方式是更彻底的解法。核心思路是找到你原本想用getsource获取的信息用不依赖源码的方式拿到。5.1 用doc和annotations替代源码分析很多人用inspect.getsource其实只是想拿函数的文档或者参数信息。这些信息完全可以通过__doc__、__annotations__、inspect.signature拿到不需要读源码import inspect def describe(func): sig inspect.signature(func) doc func.__doc__ or (no doc) ann func.__annotations__ return f{func.__name__}{sig} - {ann}\n{doc}inspect.signature在打包环境下是完全可用的因为它只依赖__code__对象里的元信息不读源文件。这一点非常关键很多人的需求其实用signature就够了。5.2 用 co_consts 和 dis 模块做字节码级分析如果你确实需要看函数内部做了什么比如做代码审计或者自动生成测试那么可以用dis模块反汇编字节码import dis def analyze(func): print(f {func.__name__} ) dis.dis(func)dis.dis输出的是字节码指令虽然不如源码直观但在打包环境下100% 可用因为它只依赖__code__对象。我有个做静态分析的项目原本用getsource做 AST 解析打包后一直报错后来改成运行时用dis分析字节码 打包时预生成 AST 缓存问题彻底解决。5.3 用 dill 的序列化替代方案如果你的报错来自dill或cloudpickle序列化函数那么有几个选择改用pickle 顶层函数pickle只能序列化顶层定义的函数通过引用不读源码。把需要序列化的函数提到模块顶层就能绕开dill的源码读取。用dill.settings关闭源码捕获dill有个settings字典可以设置recurse、byref等参数。虽然不能完全关闭源码读取但调整后能减少触发概率。改用marshal序列化 code 对象marshal.dumps(func.__code__)可以把字节码序列化配合函数名和默认值重建函数完全不碰源码。我实测下来把函数提到顶层 用 pickle是最稳的方案代价是代码结构要调整不能再用闭包和 lambda 做序列化。5.4 给动态函数手动补元信息对于exec或compile生成的动态函数可以手动设置__doc__、__name__、__module__等属性让依赖这些信息的代码正常工作code compile(def dynamic(): return 42, dynamic, exec) namespace {} exec(code, namespace) func namespace[dynamic] func.__doc__ 动态生成的函数返回 42 func.__module__ __main__ func.__qualname__ dynamic这样即使某些库尝试读取func.__doc__也能拿到有意义的内容而不是None。当然如果库坚持要getsource那还是没辙只能改库或者换库。6. 打包参数与 hook 干预几个容易被忽略的细节除了补源码和改调用方式PyInstaller 本身的一些参数和 hook 机制也能帮上忙。这部分容易被忽略但在特定场景下非常有效。6.1 --collect-submodules 和 --collect-data 的正确用法有些库的源码读取发生在子模块里而 PyInstaller 默认可能没把子模块打进去。这时候可以用pyinstaller --onefile --console \ --collect-submodules your_lib \ --collect-data your_lib \ main.py--collect-submodules会把指定包的所有子模块都打包--collect-data会把包的数据文件包括.py源文件如果它们在包目录里一起打包。这两个参数配合使用能解决一部分库内部读源码的问题。6.2 用 hook 文件干预模块加载如果某个库在 import 时就调用inspect.getsource导致打包失败可以写一个 hook 文件来干预。在项目根目录建一个hook-your_lib.py# hook-your_lib.py import inspect # 在库被导入前先给 inspect.getsource 打个补丁 _orig_getsource inspect.getsource def _safe_getsource(obj, *args, **kwargs): try: return _orig_getsource(obj, *args, **kwargs) except OSError: return inspect.getsource _safe_getsource然后在打包时用--additional-hooks-dir .指定 hook 目录。这个 hook 会在库导入前执行把getsource替换成一个读不到就返回空字符串的版本避免异常中断打包。注意这个补丁是全局的会影响所有调用getsource的代码。如果你的项目本身依赖getsource的返回值做逻辑判断要小心空字符串带来的副作用。6.3 --exclude-module 排除惹事的库如果某个库你其实用不到只是被间接依赖进来了那最省事的办法是直接排除pyinstaller --onefile --console --exclude-module problematic_lib main.py排除之后PyInstaller 不会分析这个库也不会打包它。但如果你的代码真的在运行时 import 了它就会ModuleNotFoundError。所以这个办法只适用于确认用不到的库。6.4 打包参数速查表为了让你快速选参数我把常用参数整理成表参数作用适用场景--add-data src;src打包源码目录需要补源码--collect-submodules pkg打包包的所有子模块库内部读源码--collect-data pkg打包包的数据文件库依赖数据文件--additional-hooks-dir .指定 hook 目录需要干预导入--exclude-module pkg排除模块库用不到但惹事--console保留控制台排查阶段必用--onefile单文件模式分发方便但启动慢7. 实测踩坑记录那些文档里不会写的细节前面讲的都是应该怎么做这一节讲讲实际做的时候会遇到什么。这些细节是我踩了无数次坑才总结出来的文档里基本不会提。7.1 --onefile 模式下 _MEIPASS 的时机问题--onefile模式下PyInstaller 会在 exe 启动时把内容解压到一个临时目录路径存在sys._MEIPASS。但这个属性不是一开始就有的它在引导程序解压完成后才被设置。如果你在模块顶层import 阶段就访问sys._MEIPASS可能会AttributeError。正确的做法是用getattr(sys, _MEIPASS, None)做保护或者用getattr(sys, frozen, False)先判断是否在打包环境import sys import os if getattr(sys, frozen, False): base getattr(sys, _MEIPASS, os.path.dirname(sys.executable)) else: base os.path.dirname(os.path.abspath(__file__))这个base变量在后续做路径拼接时非常有用建议每个打包项目都加上。7.2 临时目录的清理与文件锁--onefile模式解压出来的临时目录在程序退出时会被清理。但如果你在程序运行期间打开了临时目录里的文件句柄没关闭清理会失败导致临时目录残留。更麻烦的是如果程序崩溃临时目录可能不会被清理下次启动时 PyInstaller 会新建一个目录旧的就留在那里占空间。我遇到过一次诡异的问题程序运行到一半报could not get source code排查半天发现是临时目录被安全软件锁定了linecache读文件时被拦截。解决办法是把项目目录加入安全软件白名单或者改用--onedir模式不解压到临时目录直接在当前目录运行。7.3 中文路径和空格路径的坑Windows 下如果项目路径包含中文或空格PyInstaller 的某些版本会出现路径解析异常间接导致inspect找不到源码。我建议打包时把项目放在纯英文、无空格的路径下比如D:\build\myproject而不是D:\我的项目\my project。这个坑很隐蔽因为报错信息不会提示路径问题只会说could not get source code。7.4 虚拟环境与 PyInstaller 版本匹配PyInstaller 对 Python 版本和虚拟环境比较敏感。我遇到过在某个 Python 3.9 虚拟环境里打包正常换到 3.11 就报could not get source code的情况最后发现是 PyInstaller 版本太旧不支持 3.11 的字节码格式。解决办法是升级 PyInstaller 到最新版并且在干净的虚拟环境里打包避免全局环境的包干扰。python -m venv build_env build_env\Scripts\activate pip install --upgrade pyinstaller pip install -r requirements.txt pyinstaller --onefile --console main.py这套流程看起来啰嗦但能避免 80% 的环境问题。我现在每个打包项目都单独建一个build_env打包完就删干净利落。7.5 排查清单遇到问题按这个顺序查最后给你一个排查清单遇到could not get source code时按顺序过一遍用--console重新打包拿到完整堆栈看堆栈里inspect.py上面一层是哪个文件定位触发点判断是打包期还是运行期报错写最小复现脚本确认问题可复现判断属于四类场景中的哪一类有源码 → 补源码 路径重映射无源码 → 改调用方式signature / dis / 手动元信息库内部调用 → 查库开关 / hook 干预 / 排除模块检查路径是否含中文空格、PyInstaller 版本是否匹配在干净虚拟环境里重新打包验证这套流程我用了很多次基本能覆盖绝大多数情况。真正难缠的是那些库内部调用 动态生成代码的混合场景那种情况下往往需要同时用补源码和改调用方式两套方案甚至要 fork 那个库改源码。但只要你按这个清单一步步走总能找到出路。我个人在实际操作中的体会是could not get source code从来不是 PyInstaller 的 bug而是源码在运行时不存在这个事实的正常反映。理解了这一点你就不会再去瞎试各种打包参数而是直接问自己我的代码为什么需要源码有没有不依赖源码的替代方案想清楚这个问题解决方案自然就出来了。
1. 从一次打包翻车说起OSError 是怎么冒出来的Windows 上用 PyInstaller 打包 Python 脚本本来是个挺顺手的活儿——一条命令下去dist 目录里躺着一个 exe双击就能跑发给同事或者丢到没有 Python 环境的机器上也能用。但偏偏有那么一类报错会在你打包完成、满心欢喜双击 exe 的那一刻给你当头一棒OSError: could not get source code这个报错最让人抓狂的地方在于在 PyCharm 或者命令行里直接python main.py跑得好好的一打包就炸。你甚至不知道它是打包阶段出的问题还是运行阶段出的问题因为 PyInstaller 打包时可能一声不吭直到 exe 启动才把异常抛出来。我前后在几个项目里都撞上过这个坑涉及的场景包括用了inspect.getsource()做动态分析的脚本、用了dill或cloudpickle做序列化的任务、以及一些依赖inspect.stack()做日志追踪的框架。每次排查路径都不太一样但根因其实高度收敛。这篇就把我踩过的坑、排查链路和最终稳定的解决方案完整梳理一遍尽量让你少走弯路。先说清楚这个报错到底在说什么。could not get source code是 Python 标准库inspect模块抛出来的准确地说是inspect.getsource()、inspect.getsourcelines()、inspect.findsource()这一族函数在拿不到对象的源码文本时抛出的OSError。注意它抛的是OSError而不是ImportError或AttributeError这一点很关键——它意味着 Python 认为这个对象应该有源码但去取的时候取不到。那为什么打包之后就取不到了因为 PyInstaller 打包的本质是把你的.py源文件编译成字节码塞进一个压缩归档里运行时由一个内置的引导程序解压加载。也就是说exe 运行的时候磁盘上根本没有.py源文件。inspect.getsource()的工作方式是先通过对象的__code__.co_filename找到对应的文件路径然后打开这个文件读取源码行。文件都不存在了自然就could not get source code。理解了这个机制后面所有的解决方案就都有了统一的解释框架要么让源码在运行时能被找到要么让代码根本不依赖源码。下面我按先定位、再分类、后解决的顺序展开。2. 先别急着改代码三步定位到底是哪一行触发的很多人一看到这个报错就开始瞎改加--hidden-import、换打包参数、甚至重装 PyInstaller结果越改越乱。正确的做法是先精确定位到是哪一行代码、哪个库、在什么时机触发了这个异常。我总结了一个三步定位法实测非常有效。2.1 第一步让 exe 把完整堆栈吐出来PyInstaller 打包时如果用了--windowed也就是-w参数程序是没有控制台的异常会被吞掉或者只弹一个模糊的错误框。排查阶段一定要先用带控制台的方式打包pyinstaller --onefile --console main.py然后在命令行里运行生成的 exe让完整的 traceback 打印出来。你会看到类似这样的堆栈Traceback (most recent call last): File main.py, line 42, in module File some_lib\core.py, line 118, in build File inspect.py, line 1024, in getsource File inspect.py, line 987, in getsourcelines File inspect.py, line 826, in findsource OSError: could not get source code关键信息是倒数第二三行的调用来源——是some_lib\core.py里的某一行调用了inspect.getsource。这一步能帮你锁定是我自己的代码调用的还是某个第三方库内部调用的。2.2 第二步区分打包期报错还是运行期报错这里有个容易混淆的点。有些情况下报错发生在PyInstaller 分析依赖的阶段而不是 exe 运行阶段。典型特征是打包命令执行到一半就中断控制台直接抛出OSError: could not get source code。这种情况通常是因为某个库在导入时模块顶层就调用了inspect.getsource比如某些做自动注册、自动文档生成的库。PyInstaller 在分析 import 链时会真正 import 这些模块于是触发异常。区分方法很简单如果报错出现在pyinstaller xxx.py命令的输出里且打包没生成 exe →打包期报错如果 exe 生成成功双击或命令行运行才报错 →运行期报错两者的解决思路不同打包期报错往往需要--exclude-module排除掉那个惹事的库或者用 hook 干预运行期报错则主要靠补源码或改调用方式。2.3 第三步用最小复现脚本验证假设定位到可疑库之后别急着在完整项目里改。写一个最小脚本import inspect def foo(): return 1 print(inspect.getsource(foo))先用python min_test.py跑确认正常输出。然后pyinstaller --onefile --console min_test.py打包再跑。如果这个最小脚本也报could not get source code那你就有了一个干净的复现环境可以在这个环境里快速试验各种解决方案不用每次都在大项目里折腾几分钟。我个人的经验是90% 的这类问题都能在最小复现脚本里复现剩下 10% 是特定库的特定版本行为需要单独处理。3. 根因分类四种典型触发场景与对应特征定位到具体位置之后接下来要判断它属于哪一类。我把这些年遇到的场景归成四类每一类的特征和解决方向都不一样。3.1 场景一自己的代码显式调用了 inspect.getsource这是最直接的一类。比如你写了个装饰器想自动生成文档字符串import inspect def auto_doc(func): func.__doc__ inspect.getsource(func) return func或者写了个插件系统通过inspect.getsource读取插件源码做校验。这类场景的特征是堆栈里能直接看到你自己的文件名。解决方向有两个一是改调用方式用func.__doc__、func.__code__.co_consts等不依赖源码的替代方案二是补源码把源文件一起打包进去后面第 4 节详述。3.2 场景二第三方库内部依赖源码这类最隐蔽因为报错堆栈里全是第三方库的文件名你甚至不知道它为什么要读源码。常见的重灾区包括序列化库dill、cloudpickle在序列化函数或类时会尝试读取源码来重建对象尤其是序列化 lambda、闭包、动态定义的类时。依赖注入/自动装配框架某些框架通过inspect.getsource分析函数签名和默认值。日志/追踪库为了打印调用位置会读取调用栈对应文件的源码行。测试框架pytest的某些插件在收集测试时会读源码。ORM 和 schema 库部分库通过源码分析来推断字段类型。判断方法看堆栈里inspect.py上面那一层是哪个库的文件。如果是dill\_dill.py那就是序列化问题如果是某个框架的core.py就去查那个框架的文档看有没有禁用源码分析的开关。3.3 场景三动态生成的代码对象有一类情况比较特殊代码本身就是运行时动态生成的比如用exec()、compile()或者types.FunctionType创建的函数。这类对象压根就没有对应的源文件co_filename可能是string或者一个不存在的路径。code compile(def dynamic(): return 42, dynamic, exec) namespace {} exec(code, namespace) dynamic_func namespace[dynamic] import inspect inspect.getsource(dynamic_func) # 必然报错因为 dynamic 不是真实文件这种场景下补源码是没用的因为本来就没有源码。唯一的出路是改调用方式或者给动态函数手动设置__doc__和元信息。3.4 场景四PyInstaller 的路径映射导致的假性找不到最后一类比较微妙。有时候源码文件确实被打包进去了比如你用--add-data加了.py文件但inspect还是找不到。原因是 PyInstaller 运行时会把资源解压到一个临时目录sys._MEIPASS而co_filename里记录的路径是打包前的原始路径两者对不上。这类场景的特征是你能在sys._MEIPASS目录下找到那个.py文件但inspect就是读不到。解决方法是做路径重映射把co_filename里的原始路径映射到_MEIPASS下的实际路径。这个后面第 5 节会给具体代码。为了让你快速对号入座我把四类场景整理成一张对照表场景堆栈特征是否有源码文件推荐方向自己调用 getsource堆栈含自己的文件名有改调用方式或补源码第三方库内部调用堆栈含库文件名有查库开关或补源码动态生成代码co_filename 为string等无只能改调用方式路径映射错位文件在 _MEIPASS 但读不到有位置不同路径重映射4. 补源码方案把 .py 文件塞进 exe 的正确姿势如果你的场景属于有源码但打包后找不到那么补源码是最直接的解法。核心思路是让.py文件在运行时能被inspect找到。具体有几种做法各有取舍。4.1 用 --add-data 把源码目录一起打包PyInstaller 的--add-data参数可以把任意文件或目录打包进 exe。Windows 下的语法是源路径;目标路径注意是分号Linux/macOS 是冒号pyinstaller --onefile --console --add-data src;src main.py这条命令会把项目里的src目录整个打包进去运行时解压到sys._MEIPASS/src。但这里有个坑inspect找的是co_filename里的原始路径而不是_MEIPASS下的路径。所以光加--add-data往往不够还需要配合路径重映射。4.2 运行时做路径重映射在程序入口的最前面main.py的顶部任何业务 import 之前加上这段代码import sys import os if getattr(sys, frozen, False): # 运行在 PyInstaller 打包的 exe 中 base sys._MEIPASS # 把原始源码路径映射到 _MEIPASS 下 # 假设打包时源码在 src 目录原始路径形如 .../project/src/xxx.py # 这里根据你的实际目录结构调整 def _remap(path): if not path or not path.endswith(.py): return path # 提取 src 之后的相对路径 marker os.sep src os.sep idx path.find(marker) if idx -1: return path rel path[idx len(marker):] candidate os.path.join(base, src, rel) return candidate if os.path.exists(candidate) else path # 关键inspect 内部用的是 linecache重定向 linecache 的读取 import linecache _orig_getlines linecache.getlines def _patched_getlines(filename, module_globalsNone): return _orig_getlines(_remap(filename), module_globals) linecache.getlines _patched_getlines这段代码的原理是inspect.getsource最终是通过linecache.getlines(filename)读取文件内容的。我们拦截linecache.getlines把原始路径替换成_MEIPASS下的实际路径inspect就能正常读到源码了。注意这段代码必须在任何可能触发inspect.getsource的 import 之前执行。如果某个库在 import 时就调用了inspect而你的重映射代码写在 import 之后那就来不及了。所以放在main.py最顶部是最稳妥的。4.3 用 sys.path 和file的配合技巧还有一种更土但有时更有效的办法把源码目录直接加到sys.path并确保co_filename能被解析。具体做法是在打包时用--paths指定源码目录运行时再手动把_MEIPASS加到sys.pathimport sys import os if getattr(sys, frozen, False): sys.path.insert(0, os.path.join(sys._MEIPASS, src))但说实话这个办法对inspect.getsource帮助有限因为inspect不查sys.path它只认co_filename。所以它更适合解决import 找不到模块的问题而不是getsource 找不到源码的问题。别把这两个问题搞混了。4.4 补源码方案的代价与取舍补源码不是没有代价的。最直接的影响是exe 体积变大——源码文件本身不大但如果你的项目源码有几百个文件加上--add-data后 exe 可能膨胀几 MB 到几十 MB。其次源码暴露了任何拿到 exe 的人都能在临时目录里翻到你的.py文件。如果你的代码有商业机密这一点必须权衡。我的建议是只补真正需要被 inspect 读取的那部分源码而不是整个项目。比如只有plugins目录下的插件需要被读取那就只--add-data plugins;plugins别把整个src都塞进去。5. 改调用方式从根上绕开 getsource 的几种替代方案如果你的场景属于动态生成代码或者补源码代价太大那么改调用方式是更彻底的解法。核心思路是找到你原本想用getsource获取的信息用不依赖源码的方式拿到。5.1 用doc和annotations替代源码分析很多人用inspect.getsource其实只是想拿函数的文档或者参数信息。这些信息完全可以通过__doc__、__annotations__、inspect.signature拿到不需要读源码import inspect def describe(func): sig inspect.signature(func) doc func.__doc__ or (no doc) ann func.__annotations__ return f{func.__name__}{sig} - {ann}\n{doc}inspect.signature在打包环境下是完全可用的因为它只依赖__code__对象里的元信息不读源文件。这一点非常关键很多人的需求其实用signature就够了。5.2 用 co_consts 和 dis 模块做字节码级分析如果你确实需要看函数内部做了什么比如做代码审计或者自动生成测试那么可以用dis模块反汇编字节码import dis def analyze(func): print(f {func.__name__} ) dis.dis(func)dis.dis输出的是字节码指令虽然不如源码直观但在打包环境下100% 可用因为它只依赖__code__对象。我有个做静态分析的项目原本用getsource做 AST 解析打包后一直报错后来改成运行时用dis分析字节码 打包时预生成 AST 缓存问题彻底解决。5.3 用 dill 的序列化替代方案如果你的报错来自dill或cloudpickle序列化函数那么有几个选择改用pickle 顶层函数pickle只能序列化顶层定义的函数通过引用不读源码。把需要序列化的函数提到模块顶层就能绕开dill的源码读取。用dill.settings关闭源码捕获dill有个settings字典可以设置recurse、byref等参数。虽然不能完全关闭源码读取但调整后能减少触发概率。改用marshal序列化 code 对象marshal.dumps(func.__code__)可以把字节码序列化配合函数名和默认值重建函数完全不碰源码。我实测下来把函数提到顶层 用 pickle是最稳的方案代价是代码结构要调整不能再用闭包和 lambda 做序列化。5.4 给动态函数手动补元信息对于exec或compile生成的动态函数可以手动设置__doc__、__name__、__module__等属性让依赖这些信息的代码正常工作code compile(def dynamic(): return 42, dynamic, exec) namespace {} exec(code, namespace) func namespace[dynamic] func.__doc__ 动态生成的函数返回 42 func.__module__ __main__ func.__qualname__ dynamic这样即使某些库尝试读取func.__doc__也能拿到有意义的内容而不是None。当然如果库坚持要getsource那还是没辙只能改库或者换库。6. 打包参数与 hook 干预几个容易被忽略的细节除了补源码和改调用方式PyInstaller 本身的一些参数和 hook 机制也能帮上忙。这部分容易被忽略但在特定场景下非常有效。6.1 --collect-submodules 和 --collect-data 的正确用法有些库的源码读取发生在子模块里而 PyInstaller 默认可能没把子模块打进去。这时候可以用pyinstaller --onefile --console \ --collect-submodules your_lib \ --collect-data your_lib \ main.py--collect-submodules会把指定包的所有子模块都打包--collect-data会把包的数据文件包括.py源文件如果它们在包目录里一起打包。这两个参数配合使用能解决一部分库内部读源码的问题。6.2 用 hook 文件干预模块加载如果某个库在 import 时就调用inspect.getsource导致打包失败可以写一个 hook 文件来干预。在项目根目录建一个hook-your_lib.py# hook-your_lib.py import inspect # 在库被导入前先给 inspect.getsource 打个补丁 _orig_getsource inspect.getsource def _safe_getsource(obj, *args, **kwargs): try: return _orig_getsource(obj, *args, **kwargs) except OSError: return inspect.getsource _safe_getsource然后在打包时用--additional-hooks-dir .指定 hook 目录。这个 hook 会在库导入前执行把getsource替换成一个读不到就返回空字符串的版本避免异常中断打包。注意这个补丁是全局的会影响所有调用getsource的代码。如果你的项目本身依赖getsource的返回值做逻辑判断要小心空字符串带来的副作用。6.3 --exclude-module 排除惹事的库如果某个库你其实用不到只是被间接依赖进来了那最省事的办法是直接排除pyinstaller --onefile --console --exclude-module problematic_lib main.py排除之后PyInstaller 不会分析这个库也不会打包它。但如果你的代码真的在运行时 import 了它就会ModuleNotFoundError。所以这个办法只适用于确认用不到的库。6.4 打包参数速查表为了让你快速选参数我把常用参数整理成表参数作用适用场景--add-data src;src打包源码目录需要补源码--collect-submodules pkg打包包的所有子模块库内部读源码--collect-data pkg打包包的数据文件库依赖数据文件--additional-hooks-dir .指定 hook 目录需要干预导入--exclude-module pkg排除模块库用不到但惹事--console保留控制台排查阶段必用--onefile单文件模式分发方便但启动慢7. 实测踩坑记录那些文档里不会写的细节前面讲的都是应该怎么做这一节讲讲实际做的时候会遇到什么。这些细节是我踩了无数次坑才总结出来的文档里基本不会提。7.1 --onefile 模式下 _MEIPASS 的时机问题--onefile模式下PyInstaller 会在 exe 启动时把内容解压到一个临时目录路径存在sys._MEIPASS。但这个属性不是一开始就有的它在引导程序解压完成后才被设置。如果你在模块顶层import 阶段就访问sys._MEIPASS可能会AttributeError。正确的做法是用getattr(sys, _MEIPASS, None)做保护或者用getattr(sys, frozen, False)先判断是否在打包环境import sys import os if getattr(sys, frozen, False): base getattr(sys, _MEIPASS, os.path.dirname(sys.executable)) else: base os.path.dirname(os.path.abspath(__file__))这个base变量在后续做路径拼接时非常有用建议每个打包项目都加上。7.2 临时目录的清理与文件锁--onefile模式解压出来的临时目录在程序退出时会被清理。但如果你在程序运行期间打开了临时目录里的文件句柄没关闭清理会失败导致临时目录残留。更麻烦的是如果程序崩溃临时目录可能不会被清理下次启动时 PyInstaller 会新建一个目录旧的就留在那里占空间。我遇到过一次诡异的问题程序运行到一半报could not get source code排查半天发现是临时目录被安全软件锁定了linecache读文件时被拦截。解决办法是把项目目录加入安全软件白名单或者改用--onedir模式不解压到临时目录直接在当前目录运行。7.3 中文路径和空格路径的坑Windows 下如果项目路径包含中文或空格PyInstaller 的某些版本会出现路径解析异常间接导致inspect找不到源码。我建议打包时把项目放在纯英文、无空格的路径下比如D:\build\myproject而不是D:\我的项目\my project。这个坑很隐蔽因为报错信息不会提示路径问题只会说could not get source code。7.4 虚拟环境与 PyInstaller 版本匹配PyInstaller 对 Python 版本和虚拟环境比较敏感。我遇到过在某个 Python 3.9 虚拟环境里打包正常换到 3.11 就报could not get source code的情况最后发现是 PyInstaller 版本太旧不支持 3.11 的字节码格式。解决办法是升级 PyInstaller 到最新版并且在干净的虚拟环境里打包避免全局环境的包干扰。python -m venv build_env build_env\Scripts\activate pip install --upgrade pyinstaller pip install -r requirements.txt pyinstaller --onefile --console main.py这套流程看起来啰嗦但能避免 80% 的环境问题。我现在每个打包项目都单独建一个build_env打包完就删干净利落。7.5 排查清单遇到问题按这个顺序查最后给你一个排查清单遇到could not get source code时按顺序过一遍用--console重新打包拿到完整堆栈看堆栈里inspect.py上面一层是哪个文件定位触发点判断是打包期还是运行期报错写最小复现脚本确认问题可复现判断属于四类场景中的哪一类有源码 → 补源码 路径重映射无源码 → 改调用方式signature / dis / 手动元信息库内部调用 → 查库开关 / hook 干预 / 排除模块检查路径是否含中文空格、PyInstaller 版本是否匹配在干净虚拟环境里重新打包验证这套流程我用了很多次基本能覆盖绝大多数情况。真正难缠的是那些库内部调用 动态生成代码的混合场景那种情况下往往需要同时用补源码和改调用方式两套方案甚至要 fork 那个库改源码。但只要你按这个清单一步步走总能找到出路。我个人在实际操作中的体会是could not get source code从来不是 PyInstaller 的 bug而是源码在运行时不存在这个事实的正常反映。理解了这一点你就不会再去瞎试各种打包参数而是直接问自己我的代码为什么需要源码有没有不依赖源码的替代方案想清楚这个问题解决方案自然就出来了。
