一、用途概述
uvpacker 用于在 macOS、Linux 或 Windows 上构建 Windows (win_amd64) 平台的 Python 应用分发目录。
典型问题场景：
- 开发环境在 macOS / Linux
- 目标用户主要在 Windows
- 希望交付"无需安装 Python、可直接运行"的应用
传统方案（如 PyInstaller + Windows 构建环境）存在以下问题：
- 构建依赖 Windows 环境
- 依赖解析受本地环境影响，不可复现
- 打包过程不透明，问题定位困难
uvpacker 的设计目标是：
- 明确目标平台（Windows）
- 显式依赖解析过程（基于
uv） - 构建结果可复现
- 降低跨平台分发复杂度
其输出为一个自包含目录，包含：
- CPython Embedded Runtime（Windows）
- 项目依赖（目标平台为
win_amd64） - 自动生成的
.exe启动器
该目录可直接分发，用户无需系统 Python 环境。
二、使用方法
1. 安装 uv
uvpacker 依赖 uv 运行，需先安装 uv：
curl -LsSf https://astral.sh/uv/install.sh | sh2. 基本用法
bash
uvx uvpacker path/to/project- 输入：包含
pyproject.toml的项目目录 - 输出：
dist/<project-name>
3. 指定输出目录
bash
uvx uvpacker path/to/project -o path/to/output4. 固定工具版本
bash
uvx uvpacker==0.2.1 path/to/project建议在 CI 环境中固定版本，以保证构建一致性。
5. 项目要求
目标项目需满足以下条件：
-
使用
pyproject.toml -
定义
[project.scripts]（入口脚本）[project.scripts]
uvpacker = "uvpacker:main" -
定义
[build-system][build-system]
requires = ["uv_build>=0.11.2,<0.12.0"]
build-backend = "uv_build" -
明确指定 Python 次版本：
toml
requires-python = "==3.11.*"uvpacker 会基于该约束：
- 解析对应 patch 版本（如
3.11.9） - 下载对应的 Windows Embedded Runtime
该机制用于保证 Python 运行时版本的确定性。
三、补充说明
1. 输出结构
默认输出目录结构如下：
text
dist/<project-name>/
runtime/
packages/
<script>.exeruntime/：Windows 嵌入式 Python 运行时packages/：项目及其依赖（wheel 形式）<script>.exe：入口启动器，对应[project.scripts]
运行流程：
- 启动器调用
runtime/python.exe - 修改
_pth文件，将packages/加入模块搜索路径 - 应用运行不依赖系统 Python
2. 适用范围
适用于：
- 纯 Python 项目
- 所有依赖均提供 Windows wheel
典型场景包括：
- 桌面应用（如 PySide、Qt）
- 本地服务（如 FastAPI）
- 内部工具分发
- CI/CD 自动构建发布
3. 跨平台构建边界
支持：
- 纯 Python 项目跨平台构建
不支持：
- 项目自身包含 native 扩展（C、C++、Rust 等）时的跨平台构建
对于包含 native 扩展的项目：
- 需在 Windows 环境中构建
uvpacker不尝试进行交叉编译
该限制用于保证构建过程的可靠性与可控性。
4. 与 PyInstaller 的差异
| 对比维度 | PyInstaller | uvpacker |
|---|---|---|
| 输出形式 | 单文件或少量文件 | 结构化目录 |
| 构建依赖 | 当前环境 | 显式目标平台 |
| 依赖解析 | 隐式 | 基于 uv |
| 可复现性 | 较低 | 高 |
| 跨平台构建 | 不支持 | 支持（纯 Python） |
uvpacker 更强调构建过程的确定性与工程化，而非最小分发体积。
5. 示例项目
仓库提供示例：
example/web-demo：FastAPI 应用（含静态资源）example/qt-demo：PySide6 桌面应用
用于验证不同类型应用的打包行为。
四、总结
uvpacker 提供了一种面向工程实践的解决方案，用于在非 Windows 环境中构建 Windows Python 应用：
- 构建过程显式、可控
- 依赖解析可复现
- 输出结构清晰，便于分发与集成
- 明确约束跨平台能力边界
适用于对构建稳定性和可维护性有要求的项目。