Python 打包保姆级教程：PyInstaller、Nuitka、cx_Freeze 命令与参数

Python 打包（Packaging）指将 Python 脚本或项目发布为可独立运行的可执行文件（如 .exe）或可分发的包（如 .whl、源码包）。本文介绍 PyInstaller、Nuitka、cx_Freeze 等主流工具的安装、命令、核心参数与保姆级用法，帮助你将 Python 程序分发给无 Python 环境的用户。

一、Python 打包工具对比

按目标产物分类：生成独立可执行文件（单文件/目录）与生成可分发包（wheel、源码包）。以下为常用工具对比如下。

工具	产物类型	跨平台	体积	启动速度	适用场景
PyInstaller	exe / 单文件/目录	Windows / Linux / macOS	较大	中等	桌面应用、脚本分发、快速打包
Nuitka	exe / 单文件/目录	同上	较小（编译优化）	较快	追求体积与性能、商业发布
cx_Freeze	exe / 目录	同上	中等	中等	多平台、配置灵活
py2exe	exe / 目录	仅 Windows	中等	中等	仅 Windows 目标
setuptools + wheel	.whl / .tar.gz	通用	源码级	N/A	库发布、pip 安装

数据来源：各工具官方文档与 PyPI 统计（综合整理）。

二、PyInstaller：安装与常用命令

PyInstaller 是使用最广泛的 Python 打包工具，支持单文件、目录打包与多平台。安装与基础命令如下。

2.1 安装

pip install pyinstaller

2.2 基础打包命令

以下为最常用的三种形式：

命令	说明	产物
pyinstaller main.py	默认目录模式	dist/main/ 目录 + 可执行文件
pyinstaller -F main.py	单文件模式	dist/main.exe（或 main）
pyinstaller -D main.py	显式目录模式（默认）	dist/main/ 目录

2.3 PyInstaller 核心参数一览

参数	简写	说明	示例
--onefile	-F	生成单个可执行文件	-F main.py
--onedir	-D	生成目录（默认）	-D main.py
--name	-n	指定输出名称	-n MyApp main.py
--specpath		spec 文件输出目录	--specpath ./build
--workpath		临时文件目录	--workpath ./build
--distpath		可执行文件输出目录	--distpath ./dist
--add-data		添加数据文件（源;目标）	--add-data "config.json;."
--add-binary		添加二进制文件	--add-binary "lib.dll;."
--hidden-import		隐式导入的模块	--hidden-import pkg.mod
--collect-all		收集整个包	--collect-all pandas
--noconfirm	-y	覆盖输出不确认	-y
--clean		清理缓存再打包	--clean
--noconsole	-w	无控制台窗口（GUI）	-w main.py
--console	-c	显示控制台（默认）	-c main.py
--icon	-i	指定图标	-i app.ico main.py
--uac-admin		请求管理员权限（Windows）	--uac-admin
--key		加密 Python 字节码密钥	--key 12345

路径分隔符：Windows 用 ;，Linux/macOS 用 :。可写 spec 文件做复杂配置。

三、PyInstaller 保姆级示例

按常见场景给出完整命令示例。

3.1 单文件打包（控制台程序）

pyinstaller -F -n MyScript main.py

生成 dist/MyScript.exe（Windows）或 dist/MyScript（Linux/macOS）。

3.2 GUI 程序（无控制台）

pyinstaller -F -w -i app.ico -n MyGUI main.py

单文件、无控制台、指定图标。

3.3 带数据文件

# Windows
pyinstaller -F --add-data "config.json;." --add-data "templates;templates" main.py

# Linux / macOS
pyinstaller -F --add-data "config.json:." --add-data "templates:templates" main.py

将 config.json 和 templates 目录打进包，运行时通过 sys._MEIPASS 访问。

3.4 隐式导入与大型库

pyinstaller -F --hidden-import pandas --hidden-import sklearn.utils._cython_blas --collect-all pandas main.py

解决动态导入、C 扩展等未自动收集的问题。

3.5 完整生产级命令示例

pyinstaller -F -w -y --clean \
  -n MyApp \
  -i icon.ico \
  --add-data "config.json;." \
  --hidden-import pkg.mod \
  --distpath ./release \
  main.py

四、Nuitka：安装与常用命令

Nuitka 将 Python 编译为 C，再编译为原生二进制，体积与启动速度通常优于 PyInstaller。需安装 C 编译器（如 MSVC、GCC、Clang）。

4.1 安装

pip install nuitka

4.2 Nuitka 核心参数

参数	说明	示例
--onefile	单文件输出	--onefile main.py
--standalone	独立运行（含依赖）	--standalone main.py
--output-dir	输出目录	--output-dir=dist
--output-filename	输出文件名	--output-filename=MyApp.exe
--include-data-dir	包含数据目录	--include-data-dir=./assets=assets
--include-data-files	包含数据文件	--include-data-files=config.json=.
--enable-plugin	启用插件	--enable-plugin=numpy
--nofollow-import-to	排除模块	--nofollow-import-to=test
--windows-disable-console	无控制台（Windows）	--windows-disable-console
--windows-icon-from-ico	设置图标	--windows-icon-from-ico=app.ico

4.3 Nuitka 示例命令

python -m nuitka --standalone --onefile --output-dir=dist --output-filename=MyApp.exe --windows-disable-console main.py

五、cx_Freeze：安装与常用命令

cx_Freeze 跨平台、配置灵活，常用 setup.py 或 setup.cfg 定义打包。也支持命令行。

5.1 安装

pip install cx_Freeze

5.2 命令行打包

cxfreeze main.py --target-dir=dist

5.3 setup.py 配置示例

from cx_Freeze import setup, Executable

setup(
  name="MyApp",
  version="1.0",
  executables=[Executable(
    "main.py",
    target_name="MyApp",
    icon="app.ico",
    base="Win32GUI"  # 无控制台，仅 Windows
  )],
  options={
    "build_exe": {
      "packages": ["pandas"],
      "include_files": [("config.json", "config.json")],
    }
  }
)

执行：python setup.py build

六、工具选型要素权重

基于实际打包项目经验，选型时以下要素的影响程度（相对权重，满分 100）：

说明：权重基于 Python 打包项目实践归纳，仅供参考。

七、setuptools 与 wheel：库发布

若目标是发布为 pip 可安装的库，使用 setuptools + wheel 打包源码包与 wheel。

pip install build
python -m build

或：

python setup.py sdist bdist_wheel

生成 dist/*.whl 与 dist/*.tar.gz，可上传 PyPI。若需将 Python 应用打包进 CI/CD，可参考本站《CI/CD 与持续交付实践》。

八、小结

Python 打包可根据目标选择 PyInstaller（快速上手）、Nuitka（性能与体积）、cx_Freeze（配置灵活）或 setuptools（库发布）。PyInstaller 的 -F、-w、--add-data、--hidden-import 等参数覆盖多数桌面应用场景；遇动态导入或大型库可结合 --collect-all 与 spec 文件。若需自动化构建与发布，可接入 CI/CD；若部署为 Serverless 或云函数，可阅读《Serverless 架构实践指南》。