打包发布 on 扎塔-Zata

setuptools-打包python项目为egg / 安装库函数

Mon, 28 Apr 2025 16:41:54 +0800

这是一个使用 setuptools 将 Python 项目打包为 .egg 文件的详细教程，包含源代码示例。

请注意： .egg 格式是较旧的 Python 分发格式。目前更推荐使用 .whl (Wheel) 格式，它在安装速度和兼容性方面有优势。然而，如果你确实需要创建 .egg 文件（例如，为了兼容旧系统或特定工具），可以按照以下步骤进行。

简易教程1：使用 setuptools 打包 Python 项目为 Egg

1. 项目结构

首先，你需要一个标准的 Python 项目结构。一个典型的结构如下所示：

my_package/
├── my_package/
│ ├── __init__.py
│ └── module1.py
├── setup.py
├── README.md
└── LICENSE

my_package/: 这是你的实际 Python 包目录，其中包含你的模块和代码。
my_package/__init__.py: 这个文件使 my_package 成为一个 Python 包。它可以是空的，也可以包含包的初始化代码。
my_package/module1.py: 这是一个示例模块文件，包含你的项目代码。
setup.py: 这是 setuptools 的配置文件，用于描述你的项目以及如何打包。
README.md: 项目的说明文件（推荐）。
LICENSE: 项目的许可证文件（推荐）。

2. 创建示例项目代码

在 my_package/module1.py 中添加一些示例代码：

# my_package/module1.py

def greet(name):
 """
 一个简单的问候函数。
 """
 return f"Hello, {name}!"

def farewell(name):
 """
 一个简单的告别函数。
 """
 return f"Goodbye, {name}!"

在 my_package/__init__.py 中，你可以选择导入 module1 中的函数，以便用户可以直接从 my_package 导入它们：

# my_package/__init__.py

from .module1 import greet, farewell

__version__ = "0.1.0" # 添加一个版本号

3. 创建 setup.py 文件

setup.py 文件是使用 setuptools 打包项目的核心。它包含了项目的元数据和打包指令。

# setup.py

from setuptools import setup, find_packages

setup(
 name='my_awesome_package', # 包的名称，用户将使用此名称安装
 version='0.1.0', # 包的版本号
 description='A simple example package to demonstrate egg packaging', # 包的简短描述
 long_description=open('README.md').read(), # 详细描述，通常来自 README 文件
 long_description_content_type='text/markdown', # 详细描述的格式
 author='Your Name', # 作者姓名
 author_email='your.email@example.com', # 作者邮箱
 url='https://github.com/yourusername/my_awesome_package', # 项目主页或其他 URL
 packages=find_packages(), # 自动查找项目中的所有包
 classifiers=[ # 分类器，帮助用户在 PyPI 上找到你的包
 'Programming Language :: Python :: 3',
 'License :: OSI Approved :: MIT License',
 'Operating System :: OS Independent',
 ],
 python_requires='>=3.6', # 项目所需的最低 Python 版本
 install_requires=[ # 项目依赖的第三方库
 # 例如: 'requests>=2.20.0',
 ],
 # 如果你的包包含非 Python 文件 (如数据文件), 可以使用 package_data 或 data_files
 # package_data={
 # 'my_package': ['data/*.txt'],
 # },
 # data_files=[
 # ('my_data', ['data/my_data.csv']),
 # ],

 # 定义命令行脚本 (可选)
 # entry_points={
 # 'console_scripts': [
 # 'my_script = my_package.module1:greet', # 这里的 greet 是一个可执行函数
 # ],
 # },

 # 设置为 True 以便生成 egg 文件
 zip_safe=True,
)

setup() 函数参数说明：

name: 你的包的名称。这是用户在安装时使用的名称（例如 pip install my_awesome_package）。
version: 包的版本号。遵循 Semantic Versioning 是一个好习惯。
description: 包的简短描述。
long_description: 包的详细描述，通常从 README 文件中读取。
long_description_content_type: 详细描述的格式，例如 'text/markdown'。
author 和 author_email: 作者的信息。
url: 项目的主页或代码仓库地址。
packages: 一个列表，列出项目包含的所有 Python 包。find_packages() 函数会自动查找当前目录下的所有包（包含 __init__.py 的目录）。
classifiers: 一个列表，包含描述你的项目的分类器。这些分类器有助于用户在 PyPI (Python Package Index) 上搜索和过滤包。你可以在 PyPI Classifiers 找到完整的列表。
python_requires: 指定项目兼容的 Python 版本范围。
install_requires: 一个列表，列出项目运行时依赖的第三方库。setuptools 会在安装你的包时自动安装这些依赖。
package_data: 用于包含包内部的非 Python 文件，例如数据文件、模板等。键是包名，值是文件路径模式的列表。
data_files: 用于安装不在包内部的文件到指定位置。这在打包可执行脚本或配置文件时很有用。它是一个包含 (destination, files) 元组的列表。
entry_points: 用于定义控制台脚本或其他入口点。这允许你在安装包后直接从命令行运行某个函数。
zip_safe: 如果设置为 True (默认值)，setuptools 会尝试将包打包成一个 ZIP 文件 (即 .egg)。如果你的包需要在安装后从 ZIP 文件中导入模块，并且你没有使用 pkg_resources.resource_filename() 等方法访问包内的文件，通常可以设置为 True。如果你的包需要访问包内的非 Python 文件或有特定的加载需求，可能需要设置为 False，这样包会以目录的形式安装。

4. 生成 Egg 文件

在包含 setup.py 文件的项目根目录下，打开终端或命令行，运行以下命令：

python setup.py bdist_egg

执行此命令后，setuptools 会开始构建过程。成功后，你会在项目根目录下找到一个名为 dist/ 的目录。在该目录中，你会找到生成的 .egg 文件，其名称类似于 my_awesome_package-0.1.0-py3.x.egg (其中 py3.x 表示 Python 版本)。

5. 安装和使用 Egg 文件

你可以使用 easy_install 工具来安装 .egg 文件（easy_install 是 setuptools 自带的安装工具）：

easy_install dist/my_awesome_package-0.1.0-py3.x.egg

或者，你也可以直接将 .egg 文件放置在 Python 的 sys.path 中，Python 就可以直接从中导入模块。

安装后，你就可以像安装其他 Python 包一样导入和使用你的模块了：

# 在 Python 交互式环境中或另一个脚本中
from my_package import greet, farewell

print(greet("World"))
print(farewell("User"))

注意事项和 Egg 的局限性：

兼容性问题： Egg 文件可能在不同的操作系统、Python 版本或架构上存在兼容性问题，尤其当你的项目包含编译后的扩展模块时。
安装复杂性： 相比 Wheel，Egg 的安装通常涉及更多的运行时解压和处理，可能导致安装速度较慢。
不推荐用于新项目： 如前所述，对于新的 Python 项目，强烈建议使用 Wheel 格式进行分发。Wheel 解决了 Egg 的许多缺点，提供了更好的兼容性、更快的安装速度和更简单的结构。
zip_safe=True 的影响： 当 zip_safe 为 True 时，包会被打包到 ZIP 文件中。如果你的代码需要通过文件路径访问包内部的资源（而不是使用 pkg_resources 或 importlib.resources），可能会出现问题。设置为 False 会将包安装为目录，避免这个问题。

6. 如果不打包egg文件也可以直接安装

如果第3步做好了，实际上就已经可以直接安装，在setup.py的同级目录下运行pip install .

总结

通过创建 setup.py 文件并使用 python setup.py bdist_egg 命令，你可以使用 setuptools 将你的 Python 项目打包成 .egg 文件。虽然 Egg 格式在过去很常用，但现在 Wheel 格式已成为首选。在开发新的 Python 包时，优先考虑使用 Wheel 进行分发。如果你需要为旧系统或特定需求创建 Egg 文件，本教程提供了详细的步骤和示例代码。

PyInstaller使用教程

Sun, 27 Apr 2025 10:34:51 +0800

# 将 Python 脚本打包为单个可执行文件
pyinstaller -F script.py

# 打包为目录（包含所有依赖文件）
pyinstaller -D script.py

# 指定输出目录
pyinstaller -F -o output_dir script.py

# 添加图标
pyinstaller -F -i icon.ico script.py

# 隐藏控制台窗口（适用于 GUI 程序）
pyinstaller -F -w script.py

# 添加数据文件
pyinstaller -F --add-data "file.txt;." script.py

# 添加整个目录
pyinstaller -F --add-data "folder;folder" script.py

# 清理缓存和临时文件
pyinstaller --clean script.py

# 指定程序名称
pyinstaller -F -n app_name script.py

# 调试模式（显示更多日志）
pyinstaller -F --debug all script.py

参数说明

-F, --onefile
# 打包为单个可执行文件
# 说明：将 Python 脚本及其所有依赖打包成一个独立的可执行文件。生成的单一文件包含所有库和资源，运行时会解压到临时目录。适合分发简单的应用程序，但启动速度稍慢，且文件体积较大。

-D, --onedir
# 打包为目录，包含可执行文件和依赖
# 说明：将脚本打包为一个目录，包含一个主可执行文件和所有依赖（如动态链接库、资源文件）。相比 --onefile，启动速度更快，文件管理更透明，但分发时需要整个目录。

-o PATH, --out PATH
# 指定输出目录
# 说明：设置 PyInstaller 生成的构建文件和最终输出的目录（包括 dist 和 build 文件夹）。默认情况下，输出在当前工作目录下，PATH 为自定义路径（如 -o ./my_output）。

-i ICON_FILE, --icon ICON_FILE
# 为 Windows 可执行文件添加图标
# 说明：为 Windows 平台的可执行文件指定自定义图标，ICON_FILE 通常为 .ico 文件路径（如 -i my_icon.ico）。仅适用于 Windows，其他平台忽略此选项。

-w, --windowed, --noconsole
# 隐藏控制台窗口，适合 GUI 应用
# 说明：运行程序时不显示命令行窗口，适用于基于 GUI 的应用程序（如 Tkinter、PyQt）。在 Windows 上，生成的是“窗口化”程序；在 macOS 上，生成 .app 包。注意：使用此选项后，程序的控制台输出将不可见。

--add-data "SOURCE;DEST"
# 添加额外的数据文件或目录，格式为 源路径;目标路径
# 说明：将非 Python 文件（如图片、配置文件、数据文件）包含到打包结果中。SOURCE 是文件或目录的路径，DEST 是相对打包目录的目标路径。例如，--add-data "data.txt;." 将 data.txt 放在打包根目录。Windows 用分号 ; 分隔路径，Linux/macOS 用冒号 :（如 --add-data "data.txt:."）。

--clean
# 清理 PyInstaller 的缓存
# 说明：删除 PyInstaller 在构建过程中生成的临时文件和缓存（如 build 文件夹中的缓存）。在遇到打包问题或需要全新构建时使用，有助于避免旧文件干扰。

-n NAME, --name NAME
# 指定生成的可执行文件名
# 说明：设置生成的可执行文件或目录的名称，覆盖默认的脚本文件名。例如，-n my_app 会生成名为 my_app.exe（Windows）或 my_app（Linux/macOS）的文件或目录。

--debug [all|imports|bootloader|noarchive]
# 启用调试模式，查看详细日志
# 说明：启用调试模式以输出详细日志，帮助诊断打包问题。可选值包括：
# - all：输出所有调试信息。
# - imports：显示模块导入过程。
# - bootloader：显示启动加载器的调试信息。
# - noarchive：不将依赖打包为归档，保留解包状态便于检查。
# 例如，--debug all 会输出最详细的日志。


补充说明
参数格式：短选项（如 -F）和长选项（如 --onefile）功能相同，短选项更简洁，长选项更具可读性。
平台差异：某些选项（如 -i 和 -w）主要针对 Windows，Linux/macOS 可能有不同表现。例如，-w 在 macOS 上会生成 .app 包。
路径分隔符：--add-data 的路径分隔符在 Windows 为 ;（如 file.txt;.），在 Linux/macOS 为 :（如 file.txt:.）。
常见组合：例如，pyinstaller -F -w -i icon.ico -n my_app script.py 会生成一个无控制台、带自定义图标、名为 my_app 的单一可执行文件。

一些问题的提醒

`打包时候指定了附加文件，但是打包之后附加文件是放在了__internal文件夹里面的`

我的解决方法是：

使用python代码打包，然后打包好了之后在把文件移动到和exe一个目录

`开发的时候引用脚本没有任何问题，但是打包的时候就出错？`

我的解决方法是：

最好以程序的入口文件位置作为所有脚本的位置
最好使用相对路径：我使用的是 Root_dir = os.path.dirname(os.path.realpath(sys.argv[0])) 作为我所有函数识别的根路径

其他打包工具

cx_Freeze：老牌打包工具，稳定可靠
Auto-py-to-exe：PyInstaller的GUI版本，适合新手使用
Py2exe：仅支持Windows平台的经典工具
PyStand：非常容易快捷的打包方式，只需要把源码和环境拖入制定文件夹就可以

2. 使用PyInstaller进行打包简单使用

pip install pyinstaller

# 最简单的打包
pyinstaller your_script.py

这将生成一个dist文件夹，其中包含可执行文件及其依赖。

也可以使用pyi-makespec命令生成一个.spec文件，然后在.spec文件中进行配置，最后使用pyinstaller命令进行打包。例如：
pyi-makespec your_script.py
然后在生成的.spec文件中进行配置

常用参数说明

PyInstaller提供了多个有用的参数：

基本命令格式:

pyinstaller [options] script.py

基础参数:

-F, --onefile # 打包成一个单独的可执行文件
-D, --onedir # 打包成一个文件夹(默认选项)
-n NAME # 指定生成的可执行文件名
-w, --windowed # Windows系统下不显示命令行窗口
-c, --console # 显示命令行窗口(默认)
--noconfirm # 跳过确认提示,直接覆盖现有文件

路径和文件相关:

--distpath DIR # 指定打包后的输出路径
--workpath DIR # 指定工作目录路径
--specpath DIR # 指定spec文件的生成路径
-p DIR # 添加Python路径(可多次使用)
--add-data # 添加额外的数据文件 
 # 格式: source:dest (Windows用;分隔,Linux用:分隔)
--add-binary # 添加额外的二进制文件

打包控制:

--hidden-import # 添加隐式导入的模块
--additional-hooks-dir # 指定额外的hooks目录
--runtime-hook # 指定运行时hook脚本
--exclude-module # 排除指定模块
--clean # 清理打包前的临时文件

常见实例:

最简单的单文件打包(不需确认):

pyinstaller --noconfirm -F main.py

打包成单文件且不显示控制台:

pyinstaller --noconfirm -F -w main.py

包含数据文件的打包:

# Windows
pyinstaller --noconfirm -F --add-data "resources;resources" main.py

# Linux/MacOS
pyinstaller --noconfirm -F --add-data "resources:resources" main.py

完整的生产环境打包示例:

pyinstaller --noconfirm --onefile --windowed --icon "app.ico" ^
 --hidden-import "PIL" ^
 --add-data "resources;resources" ^
 --add-data "config.yml;." ^
 --name "MyApp" ^
 main.py

配置文件说明

此外，.spec这个文件提供了可以手动写隐式导入配置的功能，在配置文件中的hiddenimports中写入，然后允许pyinstaller手动选择相关.spec文件，后面不用再接其他配置

pyinstaller -F 哔哩.spec

下面是我用于打包gradio项目的gradio源码和一个配置文件的示例，

# gradio_app.py 
import gradio as gr


def greet(name):
 return "Hello " + name + "!!"


demo = gr.Interface(fn=greet, inputs="text", outputs="text")

if __name__ == "__main__":
 demo.launch()

配置文件

生成方式：

 pyi-makespec --collect-all aiofiles --collect-all annotated_types --collect-all anyio --collect-all certifi --collect-all charset_normalizer --collect-all click --collect-all colorama --collect-all dateutil --collect-all fastapi --collect-all ffmpy --collect-all filelock --collect-all fsspec --collect-all gradio --collect-all gradio_client --collect-all groovy --collect-all h11 --collect-all httpcore --collect-all httpx --collect-all huggingface_hub --collect-all idna --collect-all jinja2 --collect-all lxml --collect-all markdown_it --collect-all markupsafe --collect-all mdurl --collect-all multipart --collect-all numpy --collect-all opencc --collect-all orjson --collect-all packaging --collect-all pandas --collect-all pillow --collect-all pip --collect-all pydantic --collect-all pydantic_core --collect-all pydub --collect-all pygments --collect-all python_multipart --collect-all pytz --collect-all requests --collect-all rich --collect-all ruff --collect-all safehttpx --collect-all semantic_version --collect-all setuptools --collect-all shellingham --collect-all sniffio --collect-all starlette --collect-all tomlkit --collect-all tqdm --collect-all typer --collect-all tzdata --collect-all urllib3 --collect-all uvicorn --collect-all websockets --collect-all wheel gradio_app.py

下面是生成得到的配置文件

# gradio_app.spec
# -*- mode: python ; coding: utf-8 -*-
from PyInstaller.utils.hooks import collect_all

datas = []
binaries = []
hiddenimports = []
tmp_ret = collect_all('aiofiles')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('annotated_types')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('anyio')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('certifi')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('charset_normalizer')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('click')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('colorama')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('dateutil')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('fastapi')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('ffmpy')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('filelock')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('fsspec')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('gradio')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('gradio_client')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('groovy')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('h11')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('httpcore')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('httpx')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('huggingface_hub')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('idna')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('jinja2')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('lxml')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('markdown_it')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('markupsafe')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('mdurl')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('multipart')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('numpy')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('opencc')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('orjson')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('packaging')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pandas')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pillow')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pip')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pydantic')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pydantic_core')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pydub')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pygments')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('python_multipart')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pytz')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('requests')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('rich')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('ruff')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('safehttpx')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('semantic_version')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('setuptools')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('shellingham')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('sniffio')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('starlette')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('tomlkit')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('tqdm')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('typer')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('tzdata')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('urllib3')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('uvicorn')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('websockets')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('wheel')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]


a = Analysis(
 ['gradio_app.py'],
 pathex=[],
 binaries=binaries,
 datas=datas,
 hiddenimports=hiddenimports,
 hookspath=[],
 hooksconfig={},
 runtime_hooks=[],
 excludes=[],
 noarchive=False,
 module_collection_mode={'gradio': 'py',},
 optimize=0,
)
pyz = PYZ(a.pure)

exe = EXE(
 pyz,
 a.scripts,
 [],
 exclude_binaries=True,
 name='gradio_app',
 debug=False,
 bootloader_ignore_signals=False,
 strip=False,
 upx=True,
 console=True,
 disable_windowed_traceback=False,
 argv_emulation=False,
 target_arch=None,
 codesign_identity=None,
 entitlements_file=None,
)
coll = COLLECT(
 exe,
 a.binaries,
 a.datas,
 strip=False,
 upx=True,
 upx_exclude=[],
 name='gradio_app',
)

1. `Analysis` 部分

Analysis 是 PyInstaller 的核心类，用于分析 Python 脚本的依赖关系并收集打包所需的文件。

['gradio_app.py']:
指定要打包的主 Python 脚本文件。这里是 gradio_app.py，表示这是应用程序的入口脚本。
pathex=[]:
指定额外的路径，PyInstaller 会在这些路径中查找模块或文件。通常为空，PyInstaller 会自动处理标准路径。如果你的项目有非标准路径的依赖，可以在这里添加。
binaries=binaries:
指定额外的二进制文件（如 DLL 文件或共享库）。binaries 是一个预定义的列表，包含需要打包的非 Python 二进制依赖。如果为空，则 PyInstaller 自动检测。
datas=datas:
指定额外的非代码文件（如图像、配置文件、HTML 模板等）。datas 是一个列表，格式通常为 [(源路径, 目标路径)]。这些文件会被打包到最终的可执行文件中。
hiddenimports=hiddenimports:
指定 PyInstaller 无法自动检测的隐式导入模块。例如，某些动态导入的模块（如 Gradio 的依赖）需要手动列出，防止打包后缺少模块。
hookspath=[]:
指定自定义 PyInstaller 钩子文件的路径。钩子文件用于处理特定模块的打包逻辑（如 Gradio 的复杂依赖）。为空时使用默认钩子。
hooksconfig={}:
提供特定模块的钩子配置。某些模块需要额外的配置来正确打包，格式为字典。
runtime_hooks=[]:
指定运行时钩子脚本，这些脚本会在可执行文件启动时运行，用于动态修改环境（如设置环境变量）。
excludes=[]:
指定要从打包中排除的模块。用于减少包体积，排除不必要的模块。
noarchive=False:
是否禁用归档模式。如果为 True，PyInstaller 不会将文件打包为压缩归档，而是直接解压到临时目录。通常保持 False。
module_collection_mode={'gradio': 'py'}:
指定模块的收集模式。'gradio': 'py' 表示 Gradio 模块以源代码形式（.py 文件）收集，而不是编译为 .pyc 文件。这在调试或某些模块不兼容编译时有用。
optimize=0:
指定 Python 字节码优化的级别。
- 0: 无优化（默认）。
- 1: 移除 assert 语句。
- 2: 移除 assert 和文档字符串。
  通常设为 0 以保留调试信息。

2. `PYZ` 部分

PYZ 用于创建 Python 字节码的压缩归档文件（.pyz 文件），包含所有 Python 模块。

a.pure:
来自 Analysis 的纯 Python 模块列表（不包括 C 扩展模块）。PYZ 将这些模块打包为一个压缩归档，供可执行文件加载。

3. `EXE` 部分

EXE 定义了最终生成的可执行文件。

pyz:
上一步生成的 PYZ 对象，包含 Python 字节码。
a.scripts:
来自 Analysis 的脚本列表，通常包括主脚本（gradio_app.py）和 PyInstaller 的启动脚本。
[]:
额外的二进制文件列表，添加到可执行文件中。此处为空，依赖已在 Analysis 中处理。
exclude_binaries=True:
是否将二进制文件排除在可执行文件之外。如果为 True，二进制文件不会嵌入 .exe 文件，而是由 COLLECT 步骤单独收集到输出目录。这减少 .exe 文件大小。
name='gradio_app':
可执行文件的名称。生成的文件将命名为 gradio_app.exe（Windows）或 gradio_app（Linux/macOS）。
debug=False:
是否启用调试模式。如果为 True，会在运行时输出详细的调试信息（如模块加载日志）。通常设为 False。
bootloader_ignore_signals=False:
是否让 PyInstaller 的引导程序（bootloader）忽略系统信号（如 SIGINT）。通常保持默认值 False。
strip=False:
是否对可执行文件进行符号剥离（移除调试符号）。设为 True 可减小文件大小，但可能影响调试。通常设为 False。
upx=True:
是否使用 UPX（Ultimate Packer for Executables）压缩可执行文件。UPX 可以显著减小文件大小，但可能导致杀毒软件误报或兼容性问题。设为 True 表示启用。
console=True:
是否生成带有控制台窗口的可执行文件。
- True: 运行时会显示命令行窗口（适合调试或 CLI 应用）。
- False: 无控制台窗口（适合 GUI 应用）。
  Gradio 应用通常是 Web 应用，可能不需要控制台，但这里设为 True。
disable_windowed_traceback=False:
是否在 Windows GUI 模式下禁用错误跟踪。如果为 True，GUI 模式下的错误不会显示详细回溯。保持 False 以便调试。
argv_emulation=False:
是否模拟命令行参数传递（主要用于 macOS）。通常设为 False。
target_arch=None:
指定目标架构（如 x86_64 或 arm64）。为 None 时，PyInstaller 自动选择当前系统架构。
codesign_identity=None:
指定 macOS 代码签名的身份。为空表示不签名。
entitlements_file=None:
指定 macOS 代码签名的权限文件。为空表示使用默认权限。

4. `COLLECT` 部分

COLLECT 将所有文件（可执行文件、二进制文件、数据文件等）收集到一个输出目录。

exe:
上一步生成的 EXE 对象，即主可执行文件。
a.binaries:
来自 Analysis 的二进制文件列表，包含依赖的 DLL、共享库等。
a.datas:
来自 Analysis 的数据文件列表，包含非代码文件。
strip=False:
是否对收集的二进制文件进行符号剥离。保持 False 以保留调试信息。
upx=True:
是否对收集的二进制文件应用 UPX 压缩。与 EXE 部分的 upx 参数类似。
upx_exclude=[]:
指定不使用 UPX 压缩的文件列表。如果某些文件压缩后会导致问题，可以在这里列出。
name='gradio_app':
输出目录的名称。所有文件将被收集到 dist/gradio_app 目录下。

注意事项:

打包前确保在虚拟环境中安装了所有依赖
如果程序引用了动态库或特殊文件,需要使用–add-data或–add-binary添加
某些模块可能需要手动添加hidden-import
建议先使用-D选项测试,确认无误后再使用-F打包

这样的参数列表更加完整,包含了–noconfirm参数的使用说明。您可以根据具体需求选择合适的参数组合。

3. 实战案例：打包一个GUI应用

下面是一个完整的案例，展示如何打包一个使用tkinter的GUI应用。

3.1 示例程序代码

import tkinter as tk
from tkinter import messagebox

class SimpleApp:
 def __init__(self, root):
 self.root = root
 self.root.title("简单计算器")

 # 创建输入框
 self.num1 = tk.Entry(root)
 self.num1.pack()

 self.num2 = tk.Entry(root)
 self.num2.pack()

 # 创建按钮
 self.calc_button = tk.Button(root, text="计算", command=self.calculate)
 self.calc_button.pack()

 # 显示结果的标签
 self.result_label = tk.Label(root, text="结果：")
 self.result_label.pack()

 def calculate(self):
 try:
 n1 = float(self.num1.get())
 n2 = float(self.num2.get())
 result = n1 + n2
 self.result_label.config(text=f"结果：{result}")
 except ValueError:
 messagebox.showerror("错误", "请输入有效的数字！")

if __name__ == "__main__":
 root = tk.Tk()
 app = SimpleApp(root)
 root.mainloop()

3.2 打包配置文件

创建一个名为 app.spec 的配置文件：

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(['your_script.py'],
 pathex=[],
 binaries=[],
 datas=[],
 hiddenimports=[],
 hookspath=[],
 hooksconfig={},
 runtime_hooks=[],
 excludes=[],
 win_no_prefer_redirects=False,
 win_private_assemblies=False,
 cipher=block_cipher,
 noarchive=False)

pyz = PYZ(a.pure, a.zipped_data,
 cipher=block_cipher)

exe = EXE(pyz,
 a.scripts,
 a.binaries,
 a.zipfiles,
 a.datas,
 [],
 name='MyApp',
 debug=False,
 bootloader_ignore_signals=False,
 strip=False,
 upx=True,
 upx_exclude=[],
 runtime_tmpdir=None,
 console=False,
 disable_windowed_traceback=False,
 target_arch=None,
 codesign_identity=None,
 entitlements_file=None,
 icon='icon.ico')

3.3 执行打包

使用配置文件进行打包：

pyinstaller app.spec

4. 常见问题及解决方案

4.1 找不到模块

如果打包后运行提示找不到某些模块，可以：

使用 --hidden-import 参数手动添加
在spec文件中的 hiddenimports 列表中添加

4.2 文件路径问题

在打包后的程序中，需要特别注意文件路径的处理：

import os
import sys

# 获取程序运行时的真实路径
if getattr(sys, 'frozen', False):
 application_path = os.path.dirname(sys.executable)
else:
 application_path = os.path.dirname(os.path.abspath(__file__))

4.3 减小文件体积

可以通过以下方法减小打包后的文件体积：

使用虚拟环境，只安装必要的依赖
使用 --exclude-module 排除不需要的模块
使用UPX压缩（如果可用）

实践建议

始终使用虚拟环境进行开发和打包
仔细检查依赖项，避免包含不必要的模块
在目标平台上测试打包后的程序
保存并管理spec文件，方便后续修改和重新打包
记录打包过程中的问题和解决方案

6. 环境相关注意事项

6.1 Python版本兼容性

建议使用与开发环境相同的Python版本进行打包
注意目标机器的系统架构(32位/64位)
某些第三方库可能与特定Python版本不兼容，需提前测试

6.2 虚拟环境使用

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

6.3 依赖管理

使用pipreqs生成准确的依赖列表：

pip install pipreqs
pipreqs ./

定期更新requirements.txt
检查并移除未使用的依赖

Pyinstaller-打包gradio项目

Sun, 27 Apr 2025 00:42:01 +0800

由于gradio库中的代码都是pyi文件，而pyinstaller 在打包时默认库中的都是pyc文件，故而需要修改spec文件，指定对gradio库下的代码进行编译。

参考： https://cloud.tencent.com/developer/article/2503987

注意上面的链接中：

打包示例（20250426）：不推荐，打包出来的文件非常大

1 代码的例子


#gradio_example.py

import gradio as gr
import numpy as np
import logging
import sys
import os

# 配置日志
logging.basicConfig(
 level=logging.INFO,
 format='%(asctime)s - %(levelname)s - %(message)s',
 handlers=[
 logging.StreamHandler(sys.stdout)
 ]
)

def classify_text(text):
 try:
 # 这里我们使用一个简单的示例分类器
 # 在实际应用中，这里可以替换为你的机器学习模型
 if len(text) < 10:
 return "短文本"
 elif len(text) < 50:
 return "中等长度文本"
 else:
 return "长文本"
 except Exception as e:
 logging.error(f"分类过程中发生错误: {str(e)}")
 return f"错误: {str(e)}"

def main():
 try:
 # 创建 Gradio 界面
 demo = gr.Interface(
 fn=classify_text,
 inputs=gr.Textbox(label="输入文本", placeholder="请输入要分类的文本..."),
 outputs=gr.Textbox(label="分类结果"),
 title="文本长度分类器",
 description="这是一个简单的文本长度分类器示例。输入文本后，它会根据文本长度返回分类结果。",
 examples=[
 ["这是一个短文本"],
 ["这是一个中等长度的文本，包含了一些描述性的内容"],
 ["这是一个非常长的文本，包含了很多详细的信息和描述，可以用来测试分类器的性能，看看它如何处理较长的输入内容。"]
 ]
 )

 # 启动界面
 logging.info("正在启动 Gradio 界面...")
 demo.launch()
 except Exception as e:
 logging.error(f"程序启动失败: {str(e)}")
 input("按回车键退出...")

if __name__ == "__main__":
 main()

2 生成.spec文件并增加一行

gradio会有很多依赖库，这些都是要的，具体可以使用pip freeze 查看依赖

pyi-makespec --onefile --collect-all aiofiles --collect-all annotated_types --collect-all anyio --collect-all certifi --collect-all charset_normalizer --collect-all click --collect-all colorama --collect-all dateutil --collect-all fastapi --collect-all ffmpy --collect-all filelock --collect-all fsspec --collect-all gradio --collect-all gradio_client --collect-all groovy --collect-all h11 --collect-all httpcore --collect-all httpx --collect-all huggingface_hub --collect-all idna --collect-all jinja2 --collect-all lxml --collect-all markdown_it --collect-all markupsafe --collect-all mdurl --collect-all multipart --collect-all numpy --collect-all opencc --collect-all orjson --collect-all packaging --collect-all pandas --collect-all pillow --collect-all pip --collect-all pydantic --collect-all pydantic_core --collect-all pydub --collect-all pygments --collect-all python_multipart --collect-all pytz --collect-all requests --collect-all rich --collect-all ruff --collect-all safehttpx --collect-all semantic_version --collect-all setuptools --collect-all shellingham --collect-all sniffio --collect-all starlette --collect-all tomlkit --collect-all tqdm --collect-all typer --collect-all tzdata --collect-all urllib3 --collect-all uvicorn --collect-all websockets --collect-all wheel gradio_example.py

然后增加一行

module_collection_mode={'gradio': 'py',},

3 使用spec文件打包exe

pyinstaller gradio.spec

python程序打包exe使用教程

Mon, 24 Feb 2025 00:00:00 +0000

Pystand

来源： https://www.zhihu.com/question/48776632/answer/2336654649

问题和注意事项

python嵌入包的版本要和开发时候的版本一致

我因为开发版本是3.11，搞了一个3.10的python嵌入包而报错

精简代码组织

PyStand.int 仅作为入口，复杂逻辑放入 script 目录的 main.py 或其他模块，方便调试和维护。路径配置：在 PyStand.int 中通过 sys.path.append 添加 script 或 script.egg 路径，确保模块可加载。

打包教程

来源： https://www.zhihu.com/question/48776632/answer/2336654649

Pyinstaller打包

如果打包成无控制台模式，你使用你打包好的软件运行程序时可能不报任何print。

打包时需要特别注意的源码编写规范

除了基本的 Python 编码规范之外,在准备程序进行打包时,还需要特别注意以下几点:

1.1 依赖管理

确保 requirements.txt 文件中列出了程序所有的依赖库
检查依赖库的版本兼容性,避免打包后出现兼容性问题
尽可能使用 pip freeze > requirements.txt 自动生成依赖列表

1.2 动态导入处理

程序中如果使用了动态导入,需要确保 PyInstaller 能够正确识别并打包
可以使用 PyInstaller --hiddenimport 选项手动指定隐藏依赖

1.3 平台兼容性

如果程序需要跨平台运行,需要确保代码本身具有良好的跨平台兼容性
针对不同平台,可能需要使用条件编译或运行时检测来适配

1.4 文件路径处理

程序中涉及文件读写操作时,需要注意处理相对路径和绝对路径
打包后的程序文件结构可能与开发环境不同,需要适当调整路径

1.5 图形界面兼容性

如果程序有图形界面,需要确保界面组件在打包后能正常工作
可能需要额外打包一些 GUI 库的依赖项

1.6 第三方库限制

某些第三方库可能不支持 PyInstaller 打包,需要提前了解并做好替代方案
对于不支持的库,可以考虑使用纯 Python 实现或寻找替代方案

1.7 运行时环境

确保程序在打包后的运行环境下能正常工作,例如环境变量、系统依赖等

目录结构

典型的目录结构 project_name/ ├── src/ │ ├── init.py │ └── main.py ├── tests/ │ ├── init.py │ └── test_main.py ├── resources/ │ ├── config.ini │ └── images/ ├── requirements.txt ├── setup.py └── README.md

文件地址如何引用

如果项目中使用到了文件

相对导入

在同一个包内部,可以使用相对导入的方式引用其他模块。 pythonCopyfrom . import some_module from .subpackage import another_module

绝对导入

跨包引用时,需要使用绝对导入的方式。 pythonCopyfrom project_name.modules import some_module from project_name.subpackage import another_module

注意事项

避免循环导入问题,可以使用 main 进行条件导入。保持导入语句的位置在文件顶部。优先使用绝对导入,相对导入仅在同一包内部使用。

打包成一个文件

pyinstaller -F main.py

打包成多个文件（软件启动速度会快点）

pyinstaller -D main.py

无控制台打包，多文件

pyinstaller -D -w main.py

其他参数

我来为您介绍 PyInstaller 的常用打包参数：

主要参数：

-F, --onefile 打包成一个独立的可执行文件
-D, --onedir 打包成一个文件夹(默认选项)
-w, --windowed 不显示命令行窗口(Windows系统)
-c, --console 显示命令行窗口(默认,Windows系统)
-n NAME 指定生成的可执行文件名
--clean 在构建之前清理临时文件

常用可选参数：

--icon=<FILE.ico> 指定可执行文件的图标
--add-data 添加额外的数据文件
--add-binary 添加额外的二进制文件
--paths 添加导入路径
--hidden-import 添加隐式导入的模块
--exclude-module 排除指定模块

高级参数：

--runtime-hook 指定运行时钩子脚本
--additional-hooks-dir 指定额外的钩子脚本目录
--version-file 指定版本文件
--manifest 指定manifest文件(Windows)
--upx-dir 指定UPX压缩工具目录
--noupx 禁用UPX压缩

使用示例：

# 打包成单个可执行文件
pyinstaller -F main.py

# 打包成单个文件并指定图标
pyinstaller -F main.py --icon=app.ico

# 打包时添加数据文件
pyinstaller -F main.py --add-data "data:data"

# 打包成文件夹并不显示控制台
pyinstaller -D -w main.py

使用配置文件.spec打包

pyinstaller your_project.spec

打包好的exe 使用时传入参数

在开发桌面应用程序时,经常需要在打包为可执行文件(EXE)后,能够向它传递参数,以实现不同的功能。下面就讲解如何在将 Python 脚本打包为 EXE 文件后,仍然可以向其传递参数。

1. 准备工作

首先,我们需要有一个简单的 Python 脚本,用于演示如何传递参数。假设我们有一个名为 main.py 的文件,内容如下:

import sys

if __name__ == '__main__':
 if len(sys.argv) > 1:
 arg1 = sys.argv[1]
 print(f"Argument passed: {arg1}")
 else:
 print("No arguments passed.")

这个脚本会检查命令行参数的数量,如果有参数传递,就会打印出第一个参数的值。

接下来,我们需要使用 PyInstaller 将这个 Python 脚本打包为可执行文件(EXE)。为此,我们创建一个名为 ExePack.py 的文件,内容如下:

import PyInstaller.__main__
import shutil
import os

PyInstaller.__main__.run([
 'main.py',
 '--onefile',
 '--name=MyApp',
 '--distpath=dist',
 '--workpath=build',
 '--specpath=.',
 '--noconsole'
])

# 删除 build 文件夹
shutil.rmtree('build', ignore_errors=True)
# 删除 .spec 文件
os.remove('MyApp.spec')

这个脚本使用 PyInstaller 将 main.py 打包为一个名为 MyApp.exe 的可执行文件,并输出到 dist 文件夹。

2. 传递参数

现在,我们需要编写一个脚本,用于运行打包好的 EXE 文件并传递参数。创建一个名为 args2exe.py 的文件,内容如下:

import subprocess
import os

def run_exe_with_args(exe_path, *args):
 """运行 exe 文件并传入参数"""
 if not os.path.exists(exe_path):
 print(f"文件不存在: {exe_path}")
 return

 command = [exe_path] + list(args)
 result = subprocess.run(command, capture_output=True, text=True)

 print("标准输出:", result.stdout)

if __name__ == '__main__':
 exe_path = os.path.join('dist', 'MyApp.exe')
 run_exe_with_args(exe_path, '参数1', '参数2')

这个脚本定义了一个 run_exe_with_args 函数,用于运行打包好的 EXE 文件并传递参数。在 if __name__ == '__main__' 部分,我们调用这个函数,传递 '参数1' 和 '参数2' 作为参数。

3. 运行

首先,运行 ExePack.py 脚本,将 main.py 打包为 MyApp.exe 可执行文件。
然后,运行 args2exe.py 脚本。这将启动 MyApp.exe 并传递参数 '参数1' 和 '参数2'。

在控制台上,你应该能看到以下输出:

Argument passed: 参数1

这就是在打包好的 EXE 文件中传递参数的方法。通过使用 subprocess 模块,我们可以运行 EXE 文件并向其传递参数,从而实现更灵活的应用程序功能。