python：pyinstaller使用指南

一、pyinstaller简介

1. pyinstaller可以讲python项目在不同平台上打包为可执行文件

2. pyinstaller打包流程：

   读取编写好的python项目–分析其中调用的模块和库，并收集其文件副本（包括python的解释器）–将副本和python项目文件封装在一个可执行文件中

二、pyinstaller的使用

1.pyInstaller在Windows/Linux/Mac环境下的使用：执行命令相同，只需要在不同环境下执行即可
2.pyinstaller的安装

pip install pyinstaller

三、pyinstaller参数意义

• -F 或 --onefile

  打包单个文件，即项目只有一个文件时使用，项目有多个文件时不要使用

pyinstaller -F xxx.py
pyinstaller --onefile xxx.py

• -D 或 --onedir
  打包多个文件，用于框架编写的代码打包

pyinstaller -D xxx.py #xxx为项目入口文件
pyinstaller --onedir xxx.py #xxx为项目入口文件

• –key=keys
  使用keys进行加密打包

pyinstalller --key=123 -F xxx.py

• -K 或 --tk
  在部署时包含TCL/TK

• -a 或 --ascii
  不包含编码，在支持unicode的python版本上默认包含所有的编码

• -d或–debug
  产生debug版本的可执行文件

• -n name 或–name=name
  指定的spec的名字

pyinstaller -F -n myproject xxx.py
pyinstaller -F --name=myproject xxx.py

• -o dir 或 --out=dir

  1.指定spec文件的生成目录dir
  2.如果没有指定且当前目录是PyInstaller的根目录,会自动创建一个用于输出(spec和生成的可执行文件)的目录
  3.如果没有指定切当前目录不是PyInstaller的根目录，则会输出到当前的目录下

• -p dir 或 --path=dir

  1.用来添加程序所用到的包的所在位置，设置导入路径(和使用pythonpath效果相似)
  2.可以用路径分割符(Windows使用分号,Linux使用冒号)分割,指定多个目录.也可以使用多个-p参数来设置多个导入路径，让Pyintaller自己去找程序需要的资源

• -w 或 --windowed 或 --noconsole
  表示去掉控制台窗口，使用Windows子系统执行，当程序启动的时候不会打开命令行(只对Windows有效)

pyinstaller -c xxx.py
pyinstaller xxx.py --noconsole

• -c 或 --nowindowed 或 --console

  表示打开控制台窗口，使用控制台子系统执行,当程序启动的时候会打开命令行(默认)(只对Windows有效)

pyinstaller -c xxx.py
pyinstaller xxx.py --console

• -i 或 --icon=<file.ioc>

  将file.ico添加为可执行文件的资源，改变程序的图标(只对Windows系统有效)

pyinstaller -F -i file.ico xxx.py
pyinstall -F --icon=<file.ioc> xxx.py

• –icon=<file.exe,n>
  将file.exe的第n个图标添加为可执行文件的资源(只对Windows系统有效)

• -v file 或 --version=file
  将verfile作为可执行文件的版本资源(只对Windows系统有效)

• -s 或 --strip
  可执行文件和共享库将run through strip.注意Cygwin的strip往往使普通的win32 Dll无法使用

• -X 或 --upx
  如果有UPX安装(执行Configure.py时检测),会压缩执行文件(Windows系统中的DLL也会)(参见note)

四、xxx.spec配置文件详解

block_cipher = None
#以py文件为输入,分析py文件的依赖模块,并生成相应的信息
a = Analysis(['xxx.py'], # 要打包.py文件名列表，和xxx.py同级可以不同添加
       pathex=['D:\\abc\\def\\project_v1.0'], # 项目路径
       binaries=[], # 程序调用外部pyd、dll文件（二进制文件路径）以数组形式传入;例:('D:\\pro\\text.dll', 'pro'),将'pdftotext.dll'pro，与原项目结构一致即可
       datas=[], # 存放的资源文件（图片、文本等静态文件）以数组形成传入;例：('D:\\static\\c.ioc','static'),将'cc.ioc'打包之后放在static目录，与原项目结构一致即可
       hiddenimports=[], # pyinstaller解析模块时可能会遗漏某些模块（not visible to the analysis phase），造成打包后执行程序时出现类似No Module named xxx;这时就需要在hiddenimports中加入遗漏的模块
       hookspath=[],
       runtime_hooks=[],
       excludes=[], # 去除不必要的模块import，写在excludes中添加此模块
       win_no_prefer_redirects=False,
       win_private_assemblies=False,
       cipher=block_cipher)

# .pyz的压缩包，包含程序运行需要的所有依赖
pyz = PYZ(a.pure, a.zipped_data, 
       cipher=block_cipher)
       
# 根据Analysis和PYZ生成单个exe程序所需要的属性及其配置
exe = EXE(pyz,
     a.scripts,
     exclude_binaries=True,
     name='xxx', # 生成exe文件的名字
     debug=False, # debug模式
     strip=False,
     upx=True,
     console=False, # 是否在打开exe文件时打开cmd命令框
     icon='C:\Users\xx.ico' ) # 设置exe程序图标，ico格式文件（16*16）
     
# 收集前三个部分的内容进行整合，生成程序所需要的依赖包，及资源文件和配置
coll = COLLECT(exe,
        a.binaries,
        a.zipfiles,
        a.datas,
        strip=False,
        upx=True,
        name='fastplot')

五、踩坑

• 编辑.spec文件路径相关

  1.windows尽量使用绝对路径，用双斜杠\
  2.linux路径/home/my_project/web
  3…路径避免使用中文

• 打包.spec文件报错：RecursionError: maximum recursion depth exceeded
  在spec文件上添加递归深度的设置

import sys
sys.setrecursionlimit(5000)

• 更换exe图标报错：
  AttributeError: module 'win32ctypes.pywin32.win32api' has no attribute 'error'
  1.图标的大小建议（64*64）: https://lvwenhan.com/convertico/
  2.图标的颜色严格限制：256，真彩色是不行的

• 打包错误：ModuleNotFoundError: No module named ‘xxxxx’
  方法1：pyinstaller -D --hidden-import="xxxxx" main.py
  方法2：在xxx.spec中配置hiddenimports=['xxxxx']

• 运行exe文件报错：Failed to excute Script main
  使用-c模式重新打包调试，找的缺失的模块，pip install安装

• 文件打包后过大
  在程序中尽量不使用import xx；而是使用 from xx import xx