概述

TUI 模式的 Agent 开发正在成为主流。但 Python 技术栈的 Agent 做完之后，一个现实问题立刻摆在面前：如何把 Agent、Python runtime、全部依赖打包成一个可分发的单文件二进制？

这不是一个新问题，但 2026 年的答案和三年前截然不同。本文从打包原理、代码安全性、启动速度、依赖兼容性、Python 版本支持等多个维度，横向对比 PyInstaller、Nuitka、PyOxidizer 三大工具，并结合最新技术趋势给出选型建议。

为什么这事儿变难了

传统 Python 应用分发依赖 pip + virtualenv，用户自行安装 Python 环境。但 Agent 场景不同：

• 目标用户未必是 Python 开发者，不应该要求他们装 Python
• Agent 是 CLI/TUI 工具，需要一个可执行文件，不是库
• 依赖链可能很深，一个 Agent 背后可能依赖 httpx、rich、litellm、pydantic 等几十个包
• 跨平台是刚需，macOS（Intel + Apple Silicon）、Linux（glibc/musl）、Windows 三大平台必须覆盖

这些约束把问题从"怎么打包"推向了"怎么打包出一个真正能用的单文件"。

核心原理

理解对比之前，先搞清楚三者根本性的架构差异：

PyInstaller — 打包器（Freezer）

PyInstaller 不编译你的代码。它做的事情是：分析 Python 代码的 import 依赖树 → 把 CPython 解释器、所有依赖的 .pyc 文件、.so/.pyd 扩展、数据文件打包到一个归档 → 用一个 C 写的 bootloader 可执行文件包裹。运行时 bootloader 解压归档到临时目录，启动内嵌的 CPython 解释器执行你的代码。

本质上是"带 Python 的自解压 zip"。

Nuitka — 编译器（Compiler）

Nuitka 真正编译你的代码。它把 Python 源码转译为 C 代码（C11 标准）→ 调用系统 C 编译器（MSVC/GCC/Clang，甚至实验性支持 Zig）编译为原生机器码 → 链接 CPython runtime 生成可执行文件。Standalone 模式下会自动收集依赖并嵌入。

本质上是"Python → C → 原生二进制"。

PyOxidizer — 嵌入器（Embedder）

PyOxidizer 用 Rust 编写，核心思路是把 CPython 解释器编译成静态库嵌入到 Rust 二进制中，Python 代码以字节码形式嵌入。它基于 python-build-standalone 项目提供的预编译 Python 发行版。

本质上是"Rust 二进制内嵌 CPython runtime"。

深度对比

代码安全性（逆向工程难度）

这是很多商业 Agent 项目最关心的维度。

结论：如果代码保护是硬需求，Nuitka 是唯一真正有效的选择。PyInstaller 的"保护"约等于没有。

启动速度

启动速度直接影响 TUI Agent 的用户体验。

关键细节：PyInstaller 的 onefile 模式每次启动都要解压全部依赖到临时目录，这在 SSD 上约 1s，HDD 上可能 3-5s。对于 CLI Agent 这种频繁启动退出的场景，体感差异非常明显。PyInstaller 的 onedir 模式启动更快，但分发变成了一个目录而不是单文件。

Nuitka 的 standalone 模式和 onefile 模式启动速度差异不大，因为代码已经编译为原生二进制。

依赖兼容性

PyInstaller 的 hooks 生态是它最大的护城河。当你的 Agent 依赖了某个冷门包发现打包后找不到模块时，大概率有人已经写过 hook 了。Nuitka 也在积极追赶，4.0 版本新增了大量包支持。

Python 版本兼容性

PyInstaller 和 Nuitka 都在积极跟进 Python 最新版本，包括 free-threaded（no-GIL）Python 3.13t 的初步支持。

构建复杂度与学习曲线

构建时间差异的根本原因：PyInstaller 只是复制+打包；Nuitka 要把每个 Python 模块转译为 C 再编译；PyOxidizer 要编译整个 CPython。

跨平台支持

三者在跨平台方面差异不大，但 Nuitka 在 Windows 上需要 MSVC，在 macOS 上需要 Xcode Command Line Tools，在 Linux 上需要 GCC/Clang——这些都是系统级 C 编译器的依赖。PyInstaller 完全不需要。

产物体积

以一个中等规模的 Agent 项目（依赖 httpx、rich、pydantic、click 等 30+ 包）为例：

差异主要来自：PyInstaller 包含完整的 CPython 和 bootloader；Nuitka 编译后可以裁剪未使用的标准库模块；PyOxidizer 可以精确控制嵌入哪些 Python 模块。

反病毒误报

这是 PyInstaller 在企业内网分发场景中的一个实际痛点。Nuitka 和 PyOxidizer 在这方面有明显优势。

项目状态与社区活跃度（2026.5）

这是选型中最容易被忽略、却最关键的维度。

PyOxidizer 已经出局。作者 Gregory Szorc 在 2024 年 3 月公开声明缩减开源活动，2024 年 12 月将 python-build-standalone 项目移交 Astral（uv 的开发商）。PyOxidizer 仓库自 2023 年以来没有实质性更新，多个 issue 讨论替代方案。2026 年不应该再选择 PyOxidizer 用于新项目。

值得注意的是，Gregory Szorc 的 python-build-standalone 在 Astral 手中持续发展，它现在是 uv 的底层 Python 发行版提供者。这个项目虽然不直接做打包，但为整个 Python 工具链提供了高质量的独立 Python 构建，Nuitka 4.0 已经原生支持 python-build-standalone 作为编译源。

2026 年新趋势：PyCrucible

2025 年中出现的 PyCrucible 是一个值得关注的新玩家。它用 Rust 编写，基于 uv 做依赖管理，核心思路与 PyInstaller 类似（打包而非编译），但利用 Rust 的性能优势和 uv 的快速依赖解析，构建速度和产物体积都有改善。

但目前（2026.5）PyCrucible 仍处于早期阶段，社区 hooks 生态远不如 PyInstaller 成熟，不适合用于复杂依赖的 Agent 项目。它代表的方向值得跟踪——Rust 驱动的打包工具可能是下一波趋势。

选型推荐

小型 Agent（单一入口，依赖 < 20 个包）

推荐：PyInstaller

• 零配置即可工作，pyinstaller --onefile main.py 一行搞定
• 社区 hooks 覆盖绝大多数常见包
• 构建速度快，适合 CI/CD 频繁构建
• 注意事项：如果对代码保护有要求，或者反病毒误报是问题，考虑换 Nuitka

中大型 Agent（多子命令，依赖 20-100+ 个包，CLI + TUI）

推荐：Nuitka

• 代码编译为原生二进制，安全性高
• 启动速度远快于 PyInstaller onefile，TUI 体验好
• 4.0 版本引入 --project 参数，支持从 pyproject.toml 自动读取配置，大幅降低配置门槛
• 内置 Anti-Bloat 机制自动裁剪未使用的模块
• 编译时间长是主要代价，但只需在 release 构建时执行
• 支持 GitHub Actions（Nuitka-Action），可配置跨平台 CI

对 PyOxidizer 的建议

不推荐用于新项目。如果现有项目基于 PyOxidizer，建议规划迁移到 Nuitka。迁移成本主要在依赖兼容性验证上，核心打包配置不需要重写。

快速决策树

需要代码保护？
├─ 是 → Nuitka
└─ 否
    ├─ 项目依赖简单（< 20 包）？
    │   ├─ 是 → PyInstaller
    │   └─ 否 → Nuitka（Anti-Bloat 更好控制产物）
    ├─ 启动速度是关键指标？
    │   └─ 是 → Nuitka
    ├─ CI 构建时间敏感？
    │   └─ 是 → PyInstaller
    └─ 反病毒误报是痛点？
        └─ 是 → Nuitka

写在最后

PyInstaller 和 Nuitka 的定位在 2026 年已经非常清晰：

• PyInstaller 是"能用"的选择：上手最快，兼容性最广，适合快速出活
• Nuitka 是"用好"的选择：编译带来安全性、性能、体验的全面优势，4.0 的 --project 和 Anti-Bloat 机制大幅缩小了与 PyInstaller 的配置复杂度差距

对于面向终端用户的 Agent 产品，Nuitka 是 2026 年的推荐默认选择。构建时间慢的问题完全可以通过 CI 缓存（Nuitka 的编译缓存机制很成熟）来解决，而启动速度、代码安全、反病毒误报这些面向用户的问题，一旦发布就无法通过更新轻易修复。

PyOxidizer 的故事则是一个警示：技术选型不能只看 stars 数和历史声望。工具的生命力取决于维护者的持续投入。当作者离开，社区没有接手时，再好的架构设计也只是一个历史项目。