Python 库手册：zipapp 打包为可执行 ZIP 归档文件

zipapp 是 Python 3.5+ 内置的标准库模块，用于将一个完整的 Python 应用目录打包为可执行 ZIP 归档文件（通常以 .pyz 结尾），并可直接通过：

python app.pyz

运行整个应用。

zipapp 是部署 Python 项目的“最轻量”方式之一，适用于需要快速交付、小型工具、脚本打包等场景。

常见应用场景：

（1）分发 Python 应用

将项目目录压缩为单文件，用户无需安装依赖包（只要依赖已包含在目录中）。

（2）构建可执行脚本

创建 .pyz 程序，像普通脚本一样运行。

（3）服务器部署

部署脚本时便于复制和更新，无需额外解压或安装流程。

（4）支持多平台运行

.pyz 文件只依赖 Python，跨平台性良好。

◆ ◆ ◆

最小使用示例

假设目录结构：

    utils.py

运行：

python -m zipapp myapp

生成：

myapp.pyz

执行：

python myapp.pyz

如果目录中包含 __main__.py，Python 会自动将其作为入口。

◆ ◆ ◆

核心概念

1、可执行 ZIP (pyz)

.pyz 文件本质上是一个标准 ZIP 文件，但遵循：

• 必须包含 __main__.py

• 使用 Python 解释器执行 zip 内的代码

2、应用入口（main）

如未使用 __main__.py，zipapp 允许使用 main 参数指定入口函数，例如：

module:callable

如：

app:main

3、Shebang（可执行头部）

Shebang 是类 Unix 系统（Linux、macOS 等）中脚本文件的首行特殊标记。

Unix 系统下可创建直接执行的文件，如：

./app.pyz

通过设置：

python -m zipapp myapp -o app.pyz -p "/usr/bin/env python3"

◆ ◆ ◆

应用举例

例 1：最简单打包

python -m zipapp myapp

生成：

myapp.pyz

只要 myapp/__main__.py 存在即可运行。

例 2：指定输出文件名

python -m zipapp myapp -o app.pyz

例 3：指定入口点（无需 main.py）

项目结构：

   add.py

add.py 内容（示例）：

    print("Hello,mediaTEA")

命令：

python -m zipapp calc -o calc.pyz -m "add:main"

那么运行时将执行 add.main()。

例 4：创建可直接运行的可执行文件（带 shebang）

./runapp

适用于 Linux/macOS。

例 5：将依赖也打包进去

zipapp 不会自动安装依赖，你需要：

pip install -r requirements.txt -t build/

然后把你的源码复制进去：

    third-party libs...

最终：

python -m zipapp build -o myapp.pyz

即可获得自包含的应用。

◆ ◆ ◆

常用函数与参数速览

zipapp 提供两种使用方式：

命令行形式：python -m zipapp

Python 接口：zipapp.create_archive()

以下为程序接口的标准说明。

zipapp.create_archive(source, target=None, interpreter=None, main=None, filter=None)

将目录或文件创建为 .pyz 归档。

参数：

source：源目录路径（必须包含 Python 文件）。也可为已有的 zip 文件。

target（可选）：输出文件名，默认在 source 同目录生成 .pyz。

interpreter（可选）：设定 shebang，例如："/usr/bin/env python3"。

main（可选）：指定应用入口，如 "module:function"。若未提供，则必须包含 __main__.py。

filter（可选）：传入函数 fn(path) -> True/False，用于决定哪些文件加入归档。

返回：

无（生成目标 .pyz 文件）。

zipapp.get_interpreter(archive)

读取 .pyz 文件的 shebang。

参数：

archive：归档文件路径。

返回：

字符串形式的解释器路径（若无 shebang，则返回 None）。

◆ ◆ ◆

补充说明

1、.pyz 文件可直接用解压工具打开。

2、zipapp 不会处理依赖安装，需要手动复制依赖目录。

3、zipapp 不支持自动编译为 .exe，如果需要生成真正的可执行文件应使用 PyInstaller、Nuitka 等。

4、大部分标准库都能正常工作。

小结

zipapp 是 Python 标准库中用于打包应用的重要工具。它无需第三方依赖即可：

将目录打包为 .pyz 单文件程序

指定入口点

创建可直接运行的 Unix 可执行文件

支持过滤与自定义 shebang

它是 Python 官方推荐的轻量部署方案，适合脚本、工具、小型服务的分发。

“点赞有美意，赞赏是鼓励”