内网 Windows 离线安装 uv：极速 Python 包管理器的部署实战

内网 Windows 离线安装 uv：极速 Python 包管理器的部署实战

引言

Python 生态中的包管理工具经历了从 pip 到 poetry 再到 pdm 的演进。而由 Astral 团队（Ruff 的创造者）开发的 uv，凭借 Rust 带来的极致速度和统一的工作流设计，正在迅速成为开发者的新宠。然而，uv 的官方安装脚本依赖网络下载，对于无法访问互联网的内网 Windows 环境，如何才能用上这款神器？

本文将提供一套从外网准备到内网配置的完整离线部署方案，让你在封闭网络中也能享受毫秒级的包安装体验。

第一部分：认识 uv------为什么值得折腾？

在开始繁琐的离线部署前，先明确一个核心问题：uv 能带来什么？

• 速度惊人 ：基于 Rust 和异步 I/O，uv pip install 通常比传统 pip 快 10-100 倍。
• 统一工作流 ：uv 不仅能替代 pip 和 pip-tools，还能替代 virtualenv、pipx，甚至能管理 Python 解释器版本。
• 项目级依赖管理 ：原生支持 pyproject.toml，生成锁文件确保可重现构建。

对于内网环境，uv 的另一个巨大优势是极小的体积 （单个可执行文件约 20 MB），且无需依赖系统 Python，这大大简化了离线部署的复杂度。

第二部分：外网准备------搜集"弹药"

在一台能访问互联网的 Windows 电脑上，完成以下准备工作。

1. 下载 uv 可执行文件

uv 是一个独立的二进制文件，不需要安装过程。

• 打开浏览器，访问 uv 的官方 GitHub Releases 页面（搜索 astral-sh/uv）。
• 在最新版本的 Assets 列表中找到 uv-x86_64-pc-windows-msvc.zip 并下载。
• 解压这个 zip 包，你会得到两个文件：uv.exe 和 uvx.exe 。
  • uv.exe 是核心命令。
  • uvx.exe 用于运行临时 Python 工具（类似于 pipx run）。

提示 ：如果你的内网机器是 32 位系统，需要寻找 i686 标识的版本，但现代企业环境几乎均为 64 位。

2. （可选）下载 Python 解释器安装包

虽然 uv 可以通过 uv python install 命令自动下载指定版本的 Python，但内网环境无法访问 python.org。你有两种选择：

• 方案 A ：手动下载 Python 离线安装包（python-3.x.x-amd64.exe），并在内网先安装好系统 Python，然后让 uv 使用它（见后文配置）。
• 方案 B ：在外网使用 uv 下载 Python 解释器的独立构建包（standalone builds），然后拷贝到内网供 uv 使用。

这里重点介绍方案 B ，因为它更符合 uv 的"全托管"理念：

在外网电脑上执行以下命令（需先有网络）：

# 在外网下载 Python 3.11 的 standalone 版本
uv python install 3.11

下载完成后，Python 解释器被缓存在 %LOCALAPPDATA%\uv\python\ 目录中。你需要将这个目录下的对应 Python 版本文件夹（例如 cpython-3.11.11-windows-x86_64-none）完整拷贝到 U 盘上。

3. 预下载 Python 第三方包（Wheel 文件）

如果你的项目有明确的依赖清单（requirements.txt 或 pyproject.toml），提前下载好所有 .whl 文件是内网高效工作的关键。

在外网电脑上，进入你的项目目录，执行：

# 创建存放离线包的目录
mkdir offline_packages

# 下载依赖到本地目录（会自动拉取所有传递依赖）
uv pip download -r requirements.txt -d offline_packages

uv 会解析所有依赖项，并将它们对应的 .whl 文件保存到 offline_packages 文件夹中。将这个文件夹一并拷贝到 U 盘。

第三部分：内网部署------让 uv 跑起来

将 U 盘中的 uv.exe、uvx.exe、Python 解释器备份目录、offline_packages 文件夹复制到内网 Windows 电脑上。

1. "安装" uv 本体

uv 是免安装的，但我们需要让系统能随时找到它。

• 在电脑上创建一个不易变动的目录，例如 C:\Tools\uv。
• 将 uv.exe 和 uvx.exe 复制到该目录中。
• 配置环境变量 PATH ：
  • 右键"此电脑" -> "属性" -> "高级系统设置" -> "环境变量"。
  • 在"系统变量"或"用户变量"中找到 Path，双击编辑。
  • 点击"新建"，输入 C:\Tools\uv，然后依次点击"确定"保存。
• 验证安装 ：打开一个新的命令提示符（CMD）窗口，输入 uv --version。如果正确输出如 uv 0.x.x 的版本信息，则说明 uv 部署成功。

2. 离线配置 Python 解释器

现在 uv 可以运行，但它还不知道 Python 在哪。我们将之前外网下载的 Python standalone 包放到 uv 的缓存目录中。

• 找到 uv 的缓存目录，通常是 C:\Users\<你的用户名>\AppData\Local\uv\python\（如果没有，自己手动创建 python 子文件夹）。
• 将 U 盘中的 Python 版本文件夹（如 cpython-3.11.11-windows-x86_64-none）完整复制进去。
• 验证：在终端执行 uv python list，你应该能看到刚刚放入的 Python 版本被列出。

替代方案 ：如果你选择手动安装系统 Python（运行 .exe 安装包），那么可以跳过上述步骤，uv 会自动检测到系统 PATH 中的 python.exe。你可以通过 uv python pin 命令固定使用该版本。

3. 离线安装项目依赖

进入你的项目代码目录，使用以下命令从本地 offline_packages 目录安装依赖：

uv pip install --no-index --find-links ./offline_packages -r requirements.txt

参数详解：

• --no-index：禁止访问 PyPI 索引，完全离线。
• --find-links ./offline_packages：指定从本地目录查找包文件。

uv 将高速扫描本地 Wheel 包并完成安装，整个过程仅需几秒。

第四部分：进阶配置与技巧

1. 将现有系统 Python 设为 uv 默认解释器

如果你希望 uv 在创建虚拟环境时默认使用系统已安装的 Python（例如 C:\Python311\python.exe），可以设置：

uv python pin cpython-3.11.11-windows-x86_64-none

或者直接用路径：

uv python pin C:\Python311\python.exe

2. 搭建内网私有 PyPI 镜像源（团队级解决方案）

对于多人团队，每次都用 U 盘拷贝 offline_packages 既不高效也不易维护。更好的方案是在内网搭建一个 PyPI 镜像服务（如 devpi 或 bandersnatch），然后将 uv 指向该镜像：

uv config set index-url http://your-internal-pypi-server/simple

之后，所有 uv pip install 命令都会从内网高速下载，无需再操心离线包的问题。

3. 使用 uv venv 创建虚拟环境

uv 原生支持虚拟环境管理，速度远超 virtualenv：

# 创建虚拟环境 .venv
uv venv

# 激活环境（Windows CMD）
.venv\Scripts\activate

# 激活环境（PowerShell）
.venv\Scripts\Activate.ps1

第五部分：常见问题排查

• 问题 1：uv python install 在内网报错连接超时。

  • 原因 ：uv 尝试从 github.com/astral-sh/python-build-standalone 下载解释器。
  • 解决：必须使用第二部分所述的"外网预下载解释器并拷贝到缓存目录"的方法。

• 问题 2：uv pip install 离线安装时提示 No matching distribution found。

  • 原因 ：offline_packages 中的包与当前 Python 版本或平台（Windows 位数）不兼容。
  • 解决 ：在外网下载时，确保外网电脑的 Python 版本和位数与内网目标机器完全一致（例如都是 Python 3.11 64 位）。必要时在外网使用 uv pip download --python-platform windows --python-version 3.11 ... 来强制指定目标环境。

• 问题 3：uv 命令在 PowerShell 中无法识别，但 CMD 中可以。

  • 原因：PowerShell 的环境变量刷新机制或执行策略限制。
  • 解决 ：关闭并重新打开 PowerShell 窗口；或者以管理员身份运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

结语

uv 的设计哲学决定了它天生适合离线与 CI/CD 环境。通过本文的步骤，你可以在完全断网的 Windows 内网中成功部署并驾驭这款极速工具。一旦体验过 uv 的响应速度，再回到 pip 的漫长等待将变得难以忍受。

---