Python 打包成 exe 避坑指南PyInstaller 实战写 Python 的第十五年我被问得最多的问题之一就是我写了个脚本怎么发给不会装 Python 的同事用答案就是 PyInstaller——把 .py 打包成 .exe双击就能跑。但 PyInstaller 这个工具说简单也简单一行命令就能打包说坑也真坑——打包出来的 exe 在你电脑上好好的发给别人就报错体积动不动就上百 MB杀软还天天报警。这篇文章我把自己踩过的坑全趟了一遍下面的截图全是我在本机真实跑出来的。一、先装 PyInstaller一行命令的事装 PyInstaller 很简单pip 一行pipinstallpyinstaller装完后敲pyinstaller --version看到版本号就说明装好了。我本机用的是 6.16.0Python 3.12。二、最小打包一行命令搞定我在 demo 目录里放了个最简单的待办清单 GUI 程序todo.py只有 960 字节。打包命令就一行pyinstaller--onefile--nameTodoApp todo.py等个几十秒终端刷一大堆 INFO 日志最后看到Build complete!就成了。打包完会生成三个东西build/中间文件可以删dist/成品目录exe 就在这里TodoApp.spec配置文件一般不用管三、–onefile vs --onedir单文件还是文件夹上面用的--onefile打包出来就是一个单独的 exe 文件11.1 MB。发给别人一个文件就完事了看着很爽。如果换成--onedir或者不写默认就是这个打包出来是一个文件夹exe 本身只有 1.7 MB但旁边多了个_internal文件夹所有依赖的 DLL、Python 解释器、库全在里面。整个文件夹加起来其实比 onefile 还大。你看_internal里塞了 60 个文件Python 解释器的 .pyd 扩展、tkinter 依赖的 tcl/tk 数据、一堆系统 DLL。这些就是你的程序跑起来需要的全部家当。onedir 模式就是把它们原封不动摊开onefile 就是把这些全压缩进一个 exe 里。怎么选模式优点缺点适用场景--onefile单文件方便分发启动慢每次都要解压到临时目录发给别人用的小程序--onedir启动快体积小不重复压缩要发一整个文件夹自己用的程序、内部工具我的建议是分发给别人就用 onefile自己用就用 onedir。onefile 启动慢的问题对一个双击就用的 GUI 程序来说1-2 秒的等待完全可以接受。四、–noconsoleGUI 程序别带黑框这是最容易忘的一个参数。你写了个 tkinter GUI 程序打包完双击运行——先蹦出来一个黑色的命令行窗口然后才弹出你的 GUI。那个黑框就是控制台窗口。加个--noconsole或者简写-w就没了pyinstaller--onefile--noconsole--nameTodoApp todo.py注意如果你是命令行程序要 print 输出、要 input 输入就别加这个参数加了你就看不到任何输出了。这个参数只给 GUI 程序用。五、这些坑我替你踩过了5.1 坑一hidden-import——你的库它找不到最常见的报错就是ModuleNotFoundError: No module named xxx。你明明装了这个库Python 脚本里也 import 了PyInstaller 打包的时候也没报错结果一运行就崩。我写了个用importlib.import_module(requests)动态导入的脚本打包时没加--hidden-import运行就报了上面这个错。原因是有些库在运行时才动态导入子模块PyInstaller 静态分析的时候发现不了。解决办法就是手动告诉它pyinstaller--onefile--hidden-importrequests --hidden-importrequests.packages.urllib3 todo.py加上--hidden-importrequests重新打包再运行就正常了——能正确输出 requests 版本号还能成功请求 PyPI API。或者直接在脚本里静态 import 一下那个找不到的模块PyInstaller 就能扫到了。5.2 坑二文件路径——别用相对路径打包完你会发现脚本里写的相对路径比如open(data.txt)全错了。因为 onefile 模式运行时程序是解压到一个临时目录里跑的你的当前工作目录根本不是 exe 所在的目录。解决办法用sys._MEIPASS找资源文件的真实路径importsys,osdefresource_path(relative_path):ifhasattr(sys,_MEIPASS):basesys._MEIPASSelse:baseos.path.abspath(.)returnos.path.join(base,relative_path)然后读文件就用resource_path(data.txt)。这个写法在开发时和打包后都能正常工作。5.3 坑三体积太大——一个 helloworld 凭什么 11 MB我那个只依赖 tkinter 的待办程序打出来 11 MB。这还是因为我用的是 Anaconda 环境里面带了一堆没用的库。如果你用的是 PyPI 官方源装的干净 Python打包出来会小不少。想再压小一点有几个办法用干净的虚拟环境打包别在 Anaconda 大环境里打加--exclude-module排除不用的模块用 UPX 压缩网上有教程但我个人觉得没必要11 MB 现在根本不算事5.4 坑四杀毒软件报毒——这个锅不是你的PyInstaller 打包出来的 exe经常被 Windows Defender、360、火绒报毒。这不是你的程序有毒而是 PyInstaller 的打包方式和某些病毒的行为很像自解压到临时目录、动态加载 DLL。解决办法跟用户解释清楚加白名单给 exe 做数字签名这个要花钱买证书别太慌只要你代码干净报毒就是误报六、给你一个能直接抄的完整命令模板折腾了这么多我整理了一个最常用的完整命令你直接改文件名就能用pyinstaller ^--onefile^--noconsole^--nameMyApp ^--iconapp.ico ^ --hidden-importrequests ^ --hidden-importPIL.Image ^ --add-dataassets;assets^ main.py每个参数的意思--onefile打单文件--noconsoleGUI 程序去黑框--nameexe 的名字--icon程序图标.ico 文件--hidden-import手动指定要包含的模块--add-data把资源文件图片、配置一起打包进去分号前面是源路径后面是打包后的路径七、总结打包就这几步PyInstaller 不难记住这几点就够了一行命令就能跑先跑通再调参数–onefile 给别人–onedir 给自己GUI 程序记得加 --noconsole报 ModuleNotFoundError 就加 --hidden-import读资源文件别用相对路径用 sys._MEIPASS体积大就换干净虚拟环境别在 Anaconda 里打打包不是什么高深技术就是个体力活。把上面这些坑都避开了你打包出来的 exe 基本就能在别人电脑上正常跑了。你打包的时候还遇到过什么奇葩报错评论区聊聊我看看能不能帮你解决。-import**5.读资源文件别用相对路径用 sys._MEIPASS6.体积大就换干净虚拟环境别在 Anaconda 里打打包不是什么高深技术就是个体力活。把上面这些坑都避开了你打包出来的 exe 基本就能在别人电脑上正常跑了。你打包的时候还遇到过什么奇葩报错评论区聊聊我看看能不能帮你解决。