Python打包工具选哪个?PyInstaller与setuptools安装指南

听雨眠
听雨眠
发布时间:2026-11-18| 7人浏览过
原创

面对Python程序打包需求,本文清晰厘清PyInstaller与setuptools的核心差异、适用场景与各自安装实操步骤,帮助读者针对库分发与独立程序分发做出准确选型。

在Python项目开发中,“打包”通常指代两种截然不同的诉求:一是把代码封装为标准的Python库(Wheel或源码包),供其他开发者通过pip安装并调用;二是把代码连同Python解释器及所有依赖打包成单一的可执行文件(如.exe),让没有安装Python环境的最终用户直接运行。setuptools用于解决前者,而PyInstaller专用于解决后者。明确分发目标即可直接作出工具选型,无需在二者之间做排他性纠结。

一、选型核心:厘清分发目标与产物差异

很多初学者在选择打包工具时容易陷入“到底是该用setuptools还是PyInstaller”的疑问中,这通常是因为把“代码分发”混淆为了单一形态。为了作出恰当的选择,首先需要看清两者在最终产物与运行环境上的根本分野:

  • setuptools(开发者生态的模块分发标准):用于构建符合PEP规范的标准分发包(.whl文件与.tar.gz源码包)。它的目标用户是Python开发者或具备Python运行环境的服务器。用户在安装时通过pip拉取并依赖本地Python环境进行解析与导入。
  • PyInstaller(终端用户的可执行程序打包器):用于将Python脚本、二进制扩展模块以及Python解释器运行时共同压缩为一个独立的可执行程序。它的目标用户是普通桌面用户或运维终端,使用该程序的机器完全不需要预先安装Python解释器。
Python打包工具选哪个?PyInstaller与setuptools安装指南
图1:setuptools 与 PyInstaller 的受众、产物形态与运行依赖对照

二、认知误区辨析:常见混淆说法说明

围绕Python打包,常常能听到“代码交付必须做成exe才算完整打包”或者“setuptools已经过时、大家都改用PyInstaller了”的说法。这些说法在特定视角下看似有其原因,但在实际开发流程中并不准确:

辨析一:“Python打包就是把脚本变成exe文件”
这一观点之所以流行,是因为很多开发者编写Python程序是为非技术同事提供自动化办公工具,双击exe是最直观的交付体验。但这只是交付的一种分支形式。在Python官方生态中,绝大多数代码分发是面向开发者的库。如果一个数据清洗库被强行打包成单一exe,它就无法在其他Python脚本中被import使用,完全失去了组件复用的价值。

辨析二:“setuptools和PyInstaller是对立替代关系”
实际上,成熟的商业软件或大型CLI工具往往结合使用两者:首先使用setuptools规范代码目录、管理版本元数据和内部依赖,确保整个工程能够作为一个标准的Python包运行;随后再利用PyInstaller指向该包的入口函数进行二进制编译,输出面向最终用户的可执行文件。两者不仅不冲突,反而常处在上下游流水线中。

三、setuptools 安装与工程打包实战

如果你的目标是编写一个库,供自己在多台机器上导入,或者发布给团队伙伴通过pip安装,setuptools是基础支撑工具。

1. 环境准备与工具安装

现代Python推荐配合独立的构建前端build与格式支持工具wheel一同使用。在激活的虚拟环境中,执行以下命令安装:

# 确保pip版本保持更新
python -m pip install --upgrade pip

# 安装setuptools、wheel及现代构建器build
pip install --upgrade setuptools wheel build
验证安装:运行 python -c "import setuptools; print(setuptools.__version__)",若能正确输出版本号(如 68.x 或更高)则说明安装成功。

2. 规范项目结构

推荐采用标准的 src/ 目录布局,并在项目根目录下提供 pyproject.toml 文件进行元数据定义,避免历史遗留 setup.py 中可能执行任意代码的安全与维护缺陷:

my_project/
├── pyproject.toml
├── README.md
└── src/
    └── my_package/
        ├── __init__.py
        └── core.py

在项目根目录创建 pyproject.toml,写入构建系统声明与包信息:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "0.1.0"
description = "这是一个示范性的Python标准分发库"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

3. 执行打包与产物验证

在包含 pyproject.toml 的根目录下,执行标准构建命令:

python -m build

命令执行完毕后,控制台会输出构建日志,并在根目录新生成的 dist/ 目录下产出两个文件:

  • my_package-0.1.0.tar.gz:标准的源码分发包(sdist)。
  • my_package-0.1.0-py3-none-any.whl:预构建的二进制分发包(wheel),pip安装时优先解析此文件。
Python打包工具选哪个?PyInstaller与setuptools安装指南
图2:基于现代 pyproject.toml 规范的 setuptools 打包构建流程

四、PyInstaller 安装与独立应用打包实战

当你的目标是交付一个独立脚本或桌面工具,受众机器没有预装Python时,PyInstaller是最常用且生态成熟的工具。

1. 安装 PyInstaller

强烈建议在纯净的虚拟环境中安装PyInstaller。如果直接在全局环境中打包,PyInstaller在静态分析时可能会将环境中残留的非必要依赖一同打包,导致产物体积大幅膨胀。

# 创建并激活专用虚拟环境(Windows平台示例)
python -m venv build_env
build_env\Scripts\activate

# 在虚拟环境中安装项目依赖及PyInstaller
pip install -r requirements.txt
pip install pyinstaller
验证安装:在终端输入 pyinstaller --version。若能正常打印出版本号(如 6.x.x),说明 PyInstaller 命令已被正确添加进环境变量中。

2. 常用打包命令与参数解析

假设我们有一个程序入口脚本 app.py,根据交付形式的不同,可选用不同参数组合:

场景一:输出单文件可执行程序(常用)

pyinstaller -F app.py

-F(或 --onefile)参数指示PyInstaller将所有运行时依赖、解释器及脚本压缩为一个单一的 app.exe(在Linux/macOS上为无后缀的可执行二进制)。该文件可独立拷给他人使用。

场景二:GUI窗口程序(不显示黑色控制台黑框)

pyinstaller -F -w app.py

-w(或 --windowed / --noconsole)参数适用于通过Tkinter、PyQt等开发的图形界面程序。它会去除运行时伴随弹出的系统命令提示符窗口。

3. 打包产物目录结构

执行完打包命令后,PyInstaller 会在项目目录下生成以下核心内容:

my_app/
├── app.py
├── app.spec           # 打包规格配置文件,可进行深度定制
├── build/             # 中间构建工作目录,打包完成后可删除
└── dist/
    └── app.exe        # 最终的可交付可执行文件
Python打包工具选哪个?PyInstaller与setuptools安装指南
图3:PyInstaller 依赖分析、封装捆绑与独立运行机制

五、全维度对比与决策指南

为了在实际项目中快速决断,下表总结了两款工具在各关键维度的直接对比:

考量维度 setuptools PyInstaller
本质功能 Python 模块与包构建工具 独立可执行应用程序打包器
核心产物 .whl (Wheel) 及 .tar.gz (sdist) .exe、ELF二进制或macOS App包
包含Python解释器 否(仅包含源代码或编译后扩展) 是(内嵌完整Python解释器与DLL依赖)
产物体积 非常小(通常几KB至几MB) 较大(通常几十MB至数百MB)
目标机器要求 必须安装Python及pip包管理器 无需安装任何Python环境,开箱即用
跨平台打包机制 纯Python包天然跨平台通用 不能交叉编译,需在对应的操作系统上分别打包
源码保护程度 开放(Wheel解压即可直接查看源码) 封装为pyc二进制字节码(仍可用反编译工具还原)
Python打包工具选哪个?PyInstaller与setuptools安装指南
图4:基于用户使用方式与运行环境的打包选型决策图

六、实践建议与避坑清单

  1. 不可交叉编译:PyInstaller 只能在当前的操作系统架构下生成对应系统的可执行文件。在 Windows 上打包只能生成 Windows 的 .exe,不能直接跨平台编译出 macOS 的 .app 或 Linux 的可执行文件。需要多平台二进制时,建议利用 GitHub Actions 等多系统 CI 矩阵分别构建。
  2. 动态资源释放逻辑:在 PyInstaller 的单文件模式(-F)下运行时,程序每次启动都会将内部捆绑的资源临时解压到操作系统的临时目录(通过 sys._MEIPASS 变量获取路径)。若脚本中使用 __file__ 获取相对路径读取图片或图标,打包后会找不到文件。请确保在代码中封装路径获取函数,优先判断 hasattr(sys, '_MEIPASS')。
  3. 使用独立虚拟环境打包:无论选用哪个工具,都在专用的虚拟环境中安装最小必要的运行依赖,能避免 setuptools 误打包开发测试代码,更能避免 PyInstaller 将无关的重型第三方库(如 pandas、torch)打入 exe 中导致体积动辄突破几百兆。
相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。