简介PyInstaller 3.5 版本完整源码压缩包面向需要将 Python 程序打包成独立可执行文件的开发者解决目标机器缺少 Python 运行环境时程序难以分发和快速部署的常见难题适用场景涵盖 Windows、Linux、macOS 等系统下的项目交付、工具发布与离线安装。压缩包总计 1307 个文件包含大量 Python 脚本、文本文档、C 语言头文件与实现文件同时配有配置文件、图标素材和构建脚本等辅助内容整体大小约 3.93MB体积不大但结构清晰覆盖打包器的主体逻辑与多平台适配实现。目前已有 2229 人学习下载。借助这些源码与脚本读者可以自行完成 PyInstaller 的安装或二次构建深入理解依赖收集、启动引导、资源封装等关键机制还可以通过规格文件、路径配置和清单文件学习 Python 打包的整体流程为排查打包异常、定制个性化可执行程序提供直接参考。 这段时间在折腾旧项目手头正好有一份pyinstaller-pyinstaller-v3.5.zip顺手把打包 Python 脚本成 exe 的完整流程重跑了一遍。网上聊 PyInstaller 的文章不少但要么直接讲最新版要么只给个命令就完事很少有把“拿到 zip 怎么装”、“怎么打包”、“装完跑不起来怎么办”串起来讲的。这篇就基于我这次实操把从解压安装到踩坑排错的过程完整记录下来也给还在用旧版本或者从离线渠道拿到源码包的朋友一个参考。PyInstaller 是干嘛的一句话说就是把 Python 脚本打包成独立可执行程序让没有装 Python 环境的电脑也能直接运行你的程序。它支持 Windows、Linux、macOS 三大平台但最常见的需求就是把.py文件打包成 Windows 下的.exe。这篇文章适合这些读者刚入门 Python、想把小工具发给同事用的人在公司内网没法直接pip install、只能靠离线包安装的人以及遇到“PyInstaller 装完却跑不起来”这类问题想一次性搞清楚原因的人。1. 为什么我用的是 3.5 这个老版本1.1 版本背后的兼容性逻辑你拿到的文件名是pyinstaller-pyinstaller-v3.5.zip这其实是 PyInstaller 官方在 GitHub Releases 里发布的源码压缩包命名规则是“仓库名-分支名-版本号”。3.5 是 2017 年左右发布的版本当时支持的 Python 版本是 2.7 和 3.3 到 3.6。放到现在看它属于一个“老古董”了但依然有相当一批人不得不用它——老项目锁定版本、内网环境无法更新、某些第三方库只兼容旧版 Python这些场景我都遇到过。如果是在 2024 年之后的新环境里从头安装我肯定优先建议你用最新版命令就一行pip install pyinstaller。但如果你拿到的就是这个 3.5 的 zip或者你的 Python 版本是 3.6 及以下那跟着这篇文章走完全没问题。理解了这一点后面遇到“版本不兼容”的报错时你就知道根源在哪里了。1.2 PyInstaller 的核心打包原理在动手之前有必要花一分钟理解 PyInstaller 的打包原理否则后面遇到问题会一头雾水。PyInstaller 做的事情本质上是“捆绑”它把你的 Python 脚本、脚本里import的所有模块、Python 解释器本身以及程序运行所需的动态链接库比如.dll文件全部拷贝到一个目录或者一个 exe 文件里。这个原理决定了两个重要结论第一打包出来的 exe 体积通常很大一个最简单的print(hello)打包出来也有 5MB 以上因为里面塞了一个完整的 Python 解释器第二打包过程中如果遇到了它“看不见”的模块比如通过字符串形式动态导入的库就会出现运行时报错“ModuleNotFoundError”。理解这两点后面排错就有方向了。2. 从 zip 压缩包到命令行可用完整安装步骤2.1 安装前的环境检查不管你是从官网下载的 zip还是同事内网传给你的安装前都要先确认 Python 环境。打开命令行输入python --version如果输出的是Python 3.6.x或更低版本那这个 3.5 的 PyInstaller 可以直接用。如果输出的是Python 3.7及以上那老老实实去用新版吧3.5 装上去大概率会报不支持。这里也顺便解释一下为什么PyInstaller 的打包过程需要解析 Python 的字节码和内部数据结构Python 每个版本的小版本升级都可能改变这些结构所以 PyInstaller 对新版 Python 的支持需要专门适配。还有一个环境细节容易被忽略PyInstaller 在 Windows 上打包时需要读取 PE 文件的导入表信息所以它依赖一个叫pefile的第三方库。如果是通过 pip 在线安装这些依赖会自动装好但如果你是完全离线的环境还需要单独准备pefile、altgraph等依赖包。2.2 解压安装的两种方式拿到pyinstaller-pyinstaller-v3.5.zip后安装方式有两种我建议优先用第一种。第一种直接用 pip 安装本地压缩包这是最省事的方式pip install pyinstaller-pyinstaller-v3.5.zippip 会自动识别压缩包里的setup.py完成构建和安装并且自动处理依赖前提是能访问 PyPI或者本地已经备好了依赖包。第二种手动解压后运行 setup.py# 解压 unzip pyinstaller-pyinstaller-v3.5.zip # 进入目录注意实际解压出来的文件夹名可能略有不同 cd pyinstaller-pyinstaller-3.5 # 安装 python setup.py install这种方式本质上和第一种没区别只是把“解压”这个动作拆开做了。手动解压的好处是你可以在安装前看看源码结构坏处是如果依赖缺失你得到的是裸的报错信息需要手动去补装依赖。2.3 验证安装是否成功安装完成后验证一下是否装好pyinstaller --version如果输出版本号说明安装成功。但实际工作中这一步经常出问题最常见的就是“pyinstaller 不是内部或外部命令”。原因是 pip 安装的可执行文件位于 Python 安装目录下的Scripts子目录而这个目录没有被加入系统的 PATH 环境变量。解决办法有两个要么把C:\Users\你的用户名\AppData\Local\Programs\Python\Python36\Scripts添加到系统环境变量要么绕开命令使用模块方式调用python -m PyInstaller --version我自己更习惯用python -m PyInstaller这种方式因为它不依赖 PATH 配置环境变了也不影响。后面的打包命令也都基于这种方式。3. 打包 exe从零到一的完整实操3.1 写一个测试脚本安装验证通过后先拿一个简单的脚本练手。我建了一个hello.py内容就是一个带输入输出的小程序print(你好我是打包测试程序) input(按回车键退出...)这里故意加了一个input()作用是在双击 exe 运行时让窗口停下来等待输入方便我们确认程序确实跑起来了。如果你不加程序执行完会瞬间闪退你根本看不清结果。3.2 常用打包参数逐个拆解PyInstaller 打包命令的基本格式是python -m PyInstaller [参数] 你的脚本.py第一次打包的人只要记住下面这几个参数就够用了参数作用使用场景-F/--onefile打包成单个 exe 文件想发给别人一个文件最常用-D/--onedir打包成文件夹默认模式追求启动速度、方便调试-w/--windowed运行时不显示控制台窗口GUI 程序必加-i/--icon指定 exe 图标美化程序图标--name指定生成的 exe 名称自定义程序名--hidden-import手动指定隐藏导入的模块动态导入的库打包时用--add-data添加额外数据文件配置文件、图片、音频等这里我特别说明一下-F和-D的选择。-F打包出的单文件看似方便但每次启动PyInstaller 都要把这里面的解释器和依赖库解压到系统临时目录才能运行所以启动速度明显偏慢有些杀毒软件还会额外扫描这个解压过程。-D模式生成的是一个大文件夹里面有 exe 和一些动态库文件启动速度快但分发时得把整个文件夹压缩发过去。如果是给同事用一个工具类软件我建议-F单文件省得对方搞不清文件夹里哪些文件必须保留。3.3 一次完整的打包过程演示我用带图形界面的方式来演示因为-w参数是 GUI 程序打包的标配。新建app.pyimport tkinter as tk root tk.Tk() root.title(PyInstaller 打包测试) label tk.Label(root, text打包成功) label.pack(padx20, pady20) root.mainloop()然后执行python -m PyInstaller -F -w --name 测试程序 app.py命令执行过程中PyInstaller 会先分析导入依赖再生成一个.spec配置文件接着执行构建流程。这几步如果你是在终端里看到的最后出现completed successfully就说明打包成功了。去dist目录下就能看到生成的 exe 文件。还有一个实战小技巧打包完成后PyInstaller 会在当前目录生成三个东西——build目录构建过程产生的临时文件、dist目录最终产物、和.spec文件配置文件。发布时只需要dist里的内容build目录可以随时删除下次打包会自动重建。.spec文件建议保留因为如果你后续要调整打包参数比如更换图标直接改.spec文件再执行python -m PyInstaller 测试程序.spec比重新敲一长串命令更方便。4. 安装完运行不了这些坑我全踩过4.1 pyinstaller 命令本身跑不起来这个问题分两种情况一种是安装阶段就出错另一种是打包出来的 exe 运行阶段出错很多人会把两者混为一谈。先看安装阶段的。情况一“pyinstaller 不是内部或外部命令”。这就是前面提到的 PATH 环境变量问题。验证方法是执行python -m PyInstaller --version如果这条能正常输出版本号那就确认是可执行文件路径没被系统找到。解决把 Python 的Scripts目录加进 PATH或者干脆以后都用python -m PyInstaller这种模块调用方式。情况二安装过程中报错提示 Python 版本不受支持。例如Unsupported Python version。这说明你的 Python 版本和 PyInstaller 3.5 不匹配。我前面已经反复强调过3.5 只支持 Python 3.6 及以下。这时候要么换 Python 版本要么换 PyInstaller 版本没有第三条路。如果你被 Python 版本锁死了还有一个思路是使用pyenv这样的版本管理工具在同一台电脑上同时安装多个 Python 版本按项目切换。4.2 打包出的 exe 双击后闪退这是占比最高的运行时报错场景发生概率远超你的想象。闪退的根本原因是程序运行过程中抛出了未捕获的异常但因为没有控制台窗口错误信息一闪而过你根本来不及看。排查方法很简单先用控制台模式跑一遍。回到刚才的流程把-w参数去掉重新打包python -m PyInstaller -F app.py然后双击或在命令行里运行生成的 exe。这次因为保留了控制台窗口程序在任何一行代码报错时窗口会停下来显示完整的报错堆栈包括是哪一行代码、缺少哪个模块。我看到过最多的报错就是ModuleNotFoundError: No module named xxx原因就是我开头讲的动态导入问题。解决办法是找到报错的模块名用--hidden-import参数强制打包python -m PyInstaller -F --hidden-import xxx app.py还有一种情况比较隐蔽程序里用了文件路径比如读取config.ini。你打包成单文件模式后win 路径跟开发时跑代码路径根本就不是一回事。开发时当前工作目录是脚本所在目录打包后的 exe 运行时当前工作目录可能是C:\Windows\System32或者被解压到了系统的临时目录。想稳定获取资源文件路径要这样写import sys import os # 判断是打包环境还是开发环境 if hasattr(sys, _MEIPASS): # 打包后临时解压目录 base_dir sys._MEIPASS else: base_dir os.path.dirname(os.path.abspath(__file__)) config_path os.path.join(base_dir, config.ini)这段代码是每个用 PyInstaller 打包的程序都应该掌握的基础写法很多新人栽跟头就是栽在这里。4.3 exe 被杀毒软件拦截或误报打包后的 exe 一放到别人电脑上就被 360 或 Windows Defender 干掉这也是高频问题。原因很简单Python 程序的执行特征从临时目录释放文件、写入注册表等等与某些恶意软件行为相似。PyInstaller 打包的单文件 exe 尤其容易被误报因为它启动时要解压大量文件到临时目录然后执行。这个问题没有 100% 根治的办法但有几个缓解策略换用-D目录模式而非-F单文件模式减少解压动作误报率会降低不少。对 exe 进行代码签名签名后的程序可以显著降低杀毒软件的误报率。个人开发者可以用开源免费的签名工具或者申请各大云厂商的代码签名证书。在项目里写清楚程序来源外发时附上源码或说明文档减少被同事或客户误删的概率。4.4 打包后的 exe 在别的电脑上提示缺少 DLL这种情况主要发生在目标电脑缺少 VC 运行库时比如VCRUNTIME140.dll找不到。PyInstaller 打包的默认目标是“当前这台机器能跑”而不是“所有 Windows 机器都能跑”。如果你的开发环境里装了 Visual Studio 的运行时库而目标机器是精简版的 Windows就可能缺依赖。缓解办法有两个一是在目标机器上安装 VC 可再发行组件包二是让开发环境尽量“干净”不要在系统 Python 环境里乱装各种包用干净的虚拟环境来打包这样打包出来的产物会更接近最小依赖。5. 关于 3.5 版本与打包心得最后再聊点操作之外的体会。3.5 这个版本在今天看来确实老了缺少新版的一些优化比如对 Python 3.7 的支持、更快的构建速度、更好的资源文件处理。但它也足够稳定我在多个老项目里用了很久没出过什么幺蛾子。如果你是被迫用这个版本牢记两点第一确保 Python 版本在 3.6 及以下第二打包前用干净的虚拟环境避免把无关的包带进产物里。如果你可以自由选择版本我的建议是直接用最新版。新版本在兼容性和性能上的改进非常明显安装只需要一行pip install pyinstaller文档也更完善。但无论是哪个版本排错思路是完全一致的先用控制台模式看清楚报错再针对性地处理依赖、路径、权限这三类最常见的问题。打包这件事本质上就是“把调试期间的经验复制给别人也能用”的过程。你踩过的每一个坑都会变成下一轮更顺手的打包流程。希望这篇实操笔记帮你在 PyInstaller 上少走点弯路。本文还有配套的精品资源点击获取