K-ON

large picture of the cover

Python程序打包

Python程序打包

使用PyQt-Fluent-Widgets组件库打包举例

安装：pip install "PyQt-Fluent-Widgets[full]" -i https://pypi.org/simple/

记录可能的问题：

📢 Tips: QFluentWidgets Pro is now released. Click https://qfluentwidgets.com/pages/pro to learn more about it.

qt.qpa.plugin: Could not find the Qt platform plugin "windows" in ""
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

当前环境：

colorthief==0.2.1
darkdetect==0.8.0
numpy==2.2.6
pillow==11.3.0
PyQt-Fluent-Widgets==1.8.6
PyQt5==5.15.11
PyQt5-Frameless-Window==0.7.3
PyQt5-Qt5==5.15.2
PyQt5_sip==12.17.0
pywin32==311
scipy==1.15.3

通过检索网络，这个问题是由于PyQt环境变量问题导致

解决方法（推荐）：添加临时环境变量进行解决

  1. 在脚本处打开bash/powershell/cmd

  2. 输入 pip show pyqt5，拿到安装位置Location信息（注意后续的Location的值是自己环境的）

(demovenv) PS F:\pack_your_python> pip show pyqt5
Name: PyQt5
Version: 5.15.11
Summary: Python bindings for the Qt cross platform application toolkit
Home-page: https://www.riverbankcomputing.com/software/pyqt/
Author: 
Author-email: Riverbank Computing Limited <info@riverbankcomputing.com>
License: GPL v3
Location: f:\pack_your_python\demovenv\lib\site-packages
Requires: PyQt5-Qt5, PyQt5-sip
Required-by: PyQt-Fluent-Widgets
  1. 设置临时环境变量（注意在Location信息结尾添加\PyQt5\Qt5\plugins路径）

CMD：set QT_QPA_PLATFORM_PLUGIN_PATH="F:\pack_your_python\demovenv\Lib\site-packages\PyQt5\Qt5\plugins"

PowerShell：$env:QT_QPA_PLATFORM_PLUGIN_PATH = "F:\pack_your_python\demovenv\Lib\site-packages\PyQt5\Qt5\plugins"

LinuxBash：export QT_QPA_PLATFORM_PLUGIN_PATH="F:\pack_your_python\demovenv\Lib\site-packages\PyQt5\Qt5\plugins"

仅在当前窗口生效，需要全局永久生效请自行设置系统变量

  1. 再次启动软件即可正常运行
pyqt.png

使用Pyinstaller

安装方法：

pip install pyinstaller

使用方法：

用法: pyinstaller [-h] [-v] [-D] [-F] [--specpath DIR] [-n NAME] [--contents-directory CONTENTS_DIRECTORY] [--add-data 源文件:目标路径] [--add-binary 源文件:目标路径][-p 目录] [--hidden-import 模块名] [--collect-submodules 模块名] [--collect-data 模块名] [--collect-binaries 模块名][--collect-all 模块名] [--copy-metadata 包名] [--recursive-copy-metadata 包名] [--additional-hooks-dir 钩子路径][--runtime-hook 运行时钩子] [--exclude-module 排除模块] [--splash 图片文件] [-d {all,imports,bootloader,noarchive}] [--optimize 优化等级][--python-option PYTHON选项] [-s] [--noupx] [--upx-exclude 文件] [-c] [-w][--hide-console {hide-early,minimize-late,hide-late,minimize-early}] [-i <文件.ico 或 文件.exe,ID 或 文件.icns 或 图片或"NONE">][--disable-windowed-traceback] [--version-file 文件] [--manifest <文件或XML>] [-m <文件或XML>] [-r 资源] [--uac-admin][--uac-uiaccess] [--argv-emulation] [--osx-bundle-identifier 包标识符] [--target-architecture 架构] [--codesign-identity 签名标识][--osx-entitlements-file 授权文件] [--runtime-tmpdir 路径] [--bootloader-ignore-signals] [--distpath 输出目录] [--workpath 工作目录] [-y][--upx-dir UPX目录] [--clean] [--log-level 日志级别]脚本名 [脚本名 ...]

位置参数:

脚本名 ：要处理的脚本文件名或一个.spec文件。如果指定.spec文件，大多数选项将不必要且被忽略。

选项:

-h, --help 显示帮助信息并退出

-v, --version 显示程序版本信息并退出

--distpath 目录 打包应用的输出目录（默认: ./dist）

--workpath 工作目录 临时工作文件存放路径（.log, .pyz等）（默认: ./build）

-y, --noconfirm 覆盖输出目录（默认: SPECPATH\dist\SPECNAME）无需确认

--upx-dir UPX目录 UPX工具路径（默认: 搜索执行路径）

--clean 构建前清理PyInstaller缓存和临时文件

--log-level 级别 构建时控制台信息的详细程度。可选值: TRACE, DEBUG, INFO, WARN, DEPRECATION, ERROR, FATAL（默认: INFO）。可通过PYI_LOG_LEVEL环境变量设置。

生成模式:

-D, --onedir 创建单目录打包的可执行程序（默认）

-F, --onefile 创建单文件打包的可执行程序

--specpath 目录 生成的spec文件存放目录（默认: 当前目录）

-n --name 名称 指定打包应用和spec文件的名称（默认: 第一个脚本的主文件名）

--contents-directory 内容目录，仅对单目录模式有效，指定存放支持文件（除可执行文件外）的目录名称。使用"."可恢复旧版单目录布局。

打包内容和搜索路径:

--add-data 源文件:目标路径，添加额外的数据文件或目录到应用程序。格式应为"源文件:目标目录"，其中源文件是要收集的文件（或目录）路径，目标目录是相对于顶层应用目录的路径，两者用冒号(:)分隔。若要将文件放在顶层应用目录，使用.作为目标目录。此选项可多次使用。

--add-binary 源文件:目标路径，添加额外的二进制文件到可执行程序。格式同--add-data。此选项可多次使用。

-p, --paths 目录 添加导入搜索路径（类似PYTHONPATH）。多个路径用分号(;)分隔，或多次使用此选项。等效于在spec文件中设置pathex参数。

--hidden-import，--hiddenimport 模块名：指定脚本中不可见的隐式导入模块。此选项可多次使用。

--collect-submodules 模块名：收集指定包/模块的所有子模块。此选项可多次使用。

--collect-data , --collect-datas 模块名：收集指定包/模块的所有数据文件。此选项可多次使用。

--collect-binaries 模块名 ：收集指定包/模块的所有二进制文件。此选项可多次使用。

--collect-all 模块名 收集指定包/模块的所有子模块、数据文件和二进制文件。此选项可多次使用。

--copy-metadata 包名 复制指定包的元数据。此选项可多次使用。

--recursive-copy-metadata 包名：复制指定包及其依赖的所有元数据。此选项可多次使用。

--additional-hooks-dir 钩子路径：添加额外的钩子搜索路径。此选项可多次使用。

--runtime-hook 运行时钩子：自定义运行时钩子文件路径。运行时钩子是打包在可执行程序中的代码，在其他代码或模块之前执行以设置运行时环境特殊功能。此选项可多次使用。

--exclude-module 排除模块：忽略指定的模块或包（Python名称，非路径名称）。此选项可多次使用。

--splash 图片文件 （实验性功能）：为应用程序添加启动画面图片。启动画面可显示解压进度。

生成方式:

-d {all,imports,bootloader,noarchive}, --debug {all,imports,bootloader,noarchive}：提供调试冻结应用程序的辅助功能。可多次使用选择以下选项：

  • all: 包含以下所有选项

  • imports: 向Python解释器传递-v参数，显示模块初始化信息

  • bootloader: 显示引导程序初始化进度信息

  • noarchive: 将Python源文件作为单独文件而非归档存储

--optimize 优化等级 对收集的Python模块和脚本应用的字节码优化等级。详见PyInstaller手册"字节码优化等级"章节。

--python-option PYTHON选项：指定传递给Python解释器的命令行选项。当前支持"v"（等效于"--debug imports"）、"u"、"W <警告控制>"、"X <x选项>"和"hash_seed=<值>"。详见PyInstaller手册"指定Python解释器选项"章节。

-s, --strip 对可执行程序和共享库执行符号表剥离（Windows不推荐）

--noupx 禁用UPX压缩（即使可用）

--upx-exclude 文件 禁止UPX压缩指定二进制文件。通常用于解决UPX压缩导致的文件损坏问题。文件名不含路径。此选项可多次使用。

Windows和macOS专属选项:

-c, --console, --nowindowed：为标准I/O打开控制台窗口（默认）。Windows下若第一个脚本是.pyw文件则此选项无效。

-w, --windowed, --noconsole：Windows/macOS: 不提供标准I/O控制台窗口。macOS下会触发构建.app包。Windows下若第一个脚本是.pyw文件则自动启用。Linux系统忽略此选项。

--hide-console {hide-early,minimize-late,hide-late,minimize-early}：Windows专属: 在启用控制台的可执行程序中，自动隐藏/最小化控制台窗口（当程序拥有控制台窗口时）。

-i <文件.ico或文件.exe,ID或文件.icns或图片或"NONE">, --icon <文件.ico或文件.exe,ID或文件.icns或图片或"NONE">：Windows: 为exe应用图标。macOS: 为.app包应用图标。若图片非平台格式（Windows需ico，macOS需icns），PyInstaller尝试用Pillow转换。使用"NONE"不应用图标，显示系统默认图标（默认: 使用PyInstaller图标）。此选项可多次使用。

--disable-windowed-traceback：禁用无控制台模式下的异常追踪转储（仅Windows/macOS），改为显示功能禁用提示。

Windows专属选项:

--version-file 文件 为exe添加版本资源文件

--manifest <文件或XML> 为exe添加清单文件或XML

-m <文件或XML> --manifest的已弃用简写形式

-r , --resource 资源：添加/更新Windows可执行程序的资源。格式为FILE[,TYPE[,NAME[,LANGUAGE]]]。文件可以是数据文件或exe/dll。数据文件需指定TYPE和NAME。LANGUAGE默认为0或用通配符更新所有匹配资源。exe/dll文件若不指定TYPE/NAME/LANGUAGE（或用）则添加所有资源。此选项可多次使用。

--uac-admin 创建需要管理员权限的清单

--uac-uiaccess 允许提升权限的应用程序与远程桌面交互

macOS专属选项:

--argv-emulation 为macOS应用包启用argv模拟。启用后，初始打开文档/URL事件由引导程序处理，文件路径/URL会附加到sys.argv。

--osx-bundle-identifier 包标识符，macOS.app包标识符（用于代码签名的唯一程序名）。通常采用反向DNS命名法（如: com.mycompany.department.appname）（默认: 第一个脚本主文件名）

--target-architecture, --target-arch 架构：目标架构（仅macOS；有效值: x86_64, arm64, universal2）。支持在universal2和单架构版本间切换（需Python安装支持目标架构）。未指定时使用当前运行架构。

--codesign-identity 签名标识：（仅macOS）使用指定标识签名收集的二进制文件和生成的可执行程序。未提供时使用临时签名。

--osx-entitlements-file 授权文件：（仅macOS）代码签名时使用的授权文件。

特殊选项（极少使用）:

--runtime-tmpdir 路径：单文件模式下库文件和支持文件的解压目录。设置后引导程序将忽略操作系统定义的临时文件夹位置，在此创建_MEIxxxxxx文件夹。请谨慎使用。注意在POSIX系统上，引导程序不会对路径执行shell风格的环境变量扩展（如~或$HOME无效）。

--bootloader-ignore-signals：引导程序忽略信号而不转发给子进程。适用于例如监控进程通过进程组同时向引导程序和子进程发信号的情况，避免子进程收到重复信号。

示例实现：

  1. 下载示例软件包：PyQt-Fluent-Widgets

    单独将PyQt-Fluent-Widgets/examples/下的gallery目录拿出来即可

    目录结构：

    gallery/            # 项目根目录
└── app/            # 主应用目录
    ├── common/      # 通用模块
    ├── components/  # 组件模块
    ├── config/      # 配置文件
    ├── download/    # 下载资源
    ├── resource/    # 静态资源
    ├── view/        # 视图模块
    ├── demo.py      # Python演示文件
    └── gallery.pro  # Qt项目配置文件

  2. 尝试在已安装好的环境中启动软件：python demo.py

    启动效果如下：

    pyqt.png

  3. 执行打包命令：

    python -m PyInstaller .\PyQt-Fluent-Widgets\examples\gallery\demo.py \
    -w \
    --onedir \
    -i .\demo.ico \
    --add-data "./PyQt-Fluent-Widgets/examples/gallery/app/config/*;config" \
    --add-data "./PyQt-Fluent-Widgets/examples/gallery/app/resource/*;resource"

  4. 打包完成后dist目录结构：

    根目录结构（dist/demo/）
dist/
└── demo/                      # 主目录（由打包命令中的脚本名决定）
    ├── demo.exe               # 主可执行应用程序（第2张图显示，大小11,672KB）
    └── _internal/             # 内部依赖目录（存放所有依赖库和资源）
_internal子目录结构
_internal/
    ├── config/                  # 配置文件目录（由用户通过`--add-data`添加）
    ├── resource/                # 资源文件目录（由用户通过`--add-data`添加）
    ├── numpy/                   # NumPy库目录
    ├── numpy.libs/              # NumPy依赖的共享库
    ├── PIL/                     # Pillow图像处理库目录
    ├── PyQt5/                   # PyQt5库目录
    ├── scipy/                   # SciPy库目录
    ├── scipy.libs/              # SciPy依赖的共享库
    ├── python/                  # Python核心库（可能包含部分标准库）
    ├── Pythonwin/               # Python for Windows扩展
    ├── pywin32_system32/        # pywin32系统级文件
    ├── win32/                   # pywin32的win32 API模块
    ├── _asyncio.pyd             # 异步IO模块（Python扩展）
    ├── _bz2.pyd                 # bzip2压缩模块
    ├── _ctypes.pyd              # ctypes模块
    ├── _decimal.pyd             # 高精度小数模块
    ├── _hashlib.pyd             # 哈希算法模块
    ├── _lzma.pyd                # LZMA压缩模块
    ├── _multiprocessing.pyd     # 多进程模块
    ├── _overlapped.pyd          # Windows重叠I/O模块
    ├── _queue.pyd               # 队列模块
    ├── _socket.pyd              # 套接字模块
    ├── _sqlite3.pyd             # SQLite数据库模块
    ├── _ssl.pyd                 # SSL/TLS模块
    ├── base_library.zip         # Python标准库的压缩包
    ├── libcrypto-1_1.dll        # OpenSSL加密库
    ├── MSVCP140.dll             # Microsoft C运行时库
    ├── pyexpat.pyd              # XML解析模块
    ├── python3.dll              # Python解释器动态库（主版本）
    ├── python310.dll            # Python 3.10解释器动态库
    ├── select.pyd               # select系统调用模块
    ├── unicodedata.pyd          # Unicode数据库模块
    ├── VCRUNTIME140.dll         # Visual C++运行时
    └── VCRUNTIME140_1.dll       # Visual C++运行时扩展
    dist.png
_internal.png

  1. 双击依旧可以启动

    pyqt.png

代码下载：点击下载 pack_your_python.tar.xz

site logo

ここは軽音部でぢ

© 2025 K-ON