uv离线安装 - 技术栈

离线 CentOS 环境安装 uv 及使用 uv 管理 Python 完整教程

本教程提供一套在完全离线 CentOS 系统上安装 uv 工具，并通过 uv 安装和管理 Python 解释器的完整、可执行方案。教程分为准备阶段（联网机器） 和安装阶段（离线目标机器） 两大部分。

一、概念澄清

在使用 uv 之前，需要区分两个概念：

uv 工具：用 Rust 编写的 Python 包管理器和项目管理工具，用于创建虚拟环境、安装依赖（替代 pip、pip-tools、poetry 等）。
uv 管理的 Python 解释器 ：uv 的一个功能，允许你直接管理独立的 Python 解释器本身（类似 pyenv），通过 uv python install 命令安装特定版本的 Python。

本教程涵盖以上两者的离线安装。

二、准备阶段（在联网机器上操作）

2.1 下载 uv 静态二进制文件

uv 官方提供了静态编译的二进制文件，解压即可用，无需额外安装系统依赖库。

打开浏览器访问：https://github.com/astral-sh/uv/releases
找到最新版本（或你需要的特定版本），在 Assets 区域下载对应架构的压缩包：

架构	下载文件
x86_64（绝大多数 CentOS）	`uv-x86_64-unknown-linux-gnu.tar.gz`
ARM64 (aarch64)	`uv-aarch64-unknown-linux-gnu.tar.gz`

确认架构 ：如不确定目标机器的架构，可在 CentOS 上执行 uname -m 查看，输出 x86_64 或 aarch64。

2.2 下载 Python 预编译独立构建包

uv 安装 Python 时默认从 astral-sh/python-build-standalone 下载预编译的 Python 包。离线环境下需要提前下载好这些包。

打开浏览器访问：https://github.com/astral-sh/python-build-standalone/releases
找到包含你所需 Python 版本的 Release（例如 20250409、20241016 等）
在 Assets 区域下载对应架构的 install_only_stripped 版本（体积最小）：

例如，对于 x86_64 架构、Linux 系统、Python 3.12：
复制代码
```
cpython-3.12.10+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz
```

多版本准备 ：如果需要在离线机器上安装多个 Python 版本，请一并下载对应的 tar.gz 文件。

2.3 组织本地目录结构（关键步骤）

uv 从镜像源读取 Python 安装包时，需要特定的目录结构。下载的 tar.gz 文件需要按照 Release Tag 放入对应的子目录中。

在联网机器上创建如下目录结构：

bash 复制代码

# 创建镜像根目录
mkdir -p ~/uv-python-mirror/

# 创建以 Release Tag 命名的子目录（以 20250409 为例）
mkdir -p ~/uv-python-mirror/20250409/

# 将下载的 Python tar.gz 文件移入该子目录
mv cpython-*.tar.gz ~/uv-python-mirror/20250409/

目录结构示例：

复制代码

~/uv-python-mirror/
└── 20250409/
    ├── cpython-3.10.17+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz
    ├── cpython-3.11.12+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz
    └── cpython-3.12.10+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz

注意：子目录名称必须与 Release Tag（如 20250409）完全一致，否则 uv 无法正确识别。

三、传输文件到离线 CentOS 服务器

将以下内容通过 U 盘、SCP、SFTP 或其他可用方式拷贝到目标 CentOS 服务器的某个目录（例如 /opt/offline/）：

uv-x86_64-unknown-linux-gnu.tar.gz（uv 二进制包）
uv-python-mirror/ 整个目录（Python 预编译包镜像）

四、安装阶段（在离线 CentOS 服务器上操作）

4.1 安装 uv 工具

bash 复制代码

# 1. 进入存放安装包的目录
cd /opt/offline/

# 2. 解压 uv 二进制包
tar -xzvf uv-x86_64-unknown-linux-gnu.tar.gz

# 3. 将 uv 和 uvx 移动到系统 PATH 路径（需要 root 权限）
sudo mv uv uvx /usr/local/bin/

# 4. 验证安装
uv --version
# 应输出类似：uv 0.x.x

4.2 配置 Python 安装镜像源

将 uv 的 Python 下载源指向本地镜像目录。有两种方式：

方式一：通过环境变量（推荐，全局生效）

bash 复制代码

# 临时生效（当前终端会话）
export UV_PYTHON_INSTALL_MIRROR="file:///opt/offline/uv-python-mirror"

# 永久生效（写入 ~/.bashrc）
echo 'export UV_PYTHON_INSTALL_MIRROR="file:///opt/offline/uv-python-mirror"' >> ~/.bashrc
source ~/.bashrc

方式二：通过命令行参数（临时指定）

bash 复制代码

uv python install --mirror file:///opt/offline/uv-python-mirror 3.12

注意：file:// 协议后面跟的是镜像根目录的绝对路径 ，不是子目录路径。

4.3 使用 uv 安装 Python

配置好镜像源后，即可像在线环境一样使用 uv python install 命令安装 Python：

bash 复制代码

# 安装指定版本的 Python（精确版本号）
uv python install 3.12.10

# 或安装主版本号（uv 会自动匹配最新的补丁版本）
uv python install 3.12

uv 会自动从 file:///opt/offline/uv-python-mirror 目录下查找与 Release Tag 匹配的子目录，并在其中寻找对应版本的 tar.gz 文件进行安装。

4.4 验证 Python 安装

bash 复制代码

# 查看已安装的 Python 版本列表
uv python list

# 使用新安装的 Python 创建虚拟环境
uv venv --python 3.12 .venv

# 激活虚拟环境
source .venv/bin/activate

# 验证 Python 版本
python --version
# 应输出：Python 3.12.10

五、离线安装 Python 第三方包（扩展）

在离线环境中，除了安装 Python 解释器，通常还需要安装第三方依赖包。核心思路是：在联网机器上预先下载好所有依赖包，然后拷贝到离线机器安装。

5.1 在联网机器上下载依赖包

bash 复制代码

# 1. 创建依赖清单
echo "numpy pandas requests" > requirements.txt

# 2. 使用 uv 下载所有依赖包到本地目录
uv pip download -d ./offline-packages -r requirements.txt

5.2 传输到离线机器并安装

bash 复制代码

# 将 offline-packages 目录拷贝到离线机器后，执行：

# 激活虚拟环境
source .venv/bin/activate

# 从本地目录安装所有依赖
uv pip install --no-index --find-links ./offline-packages -r requirements.txt

参数说明：

--no-index：禁止访问 PyPI 网络索引
--find-links：指定从本地目录查找包文件

六、常见问题与排查

问题现象	可能原因及解决办法
`uv: command not found`	`uv` 未添加到 PATH。检查 `/usr/local/bin` 是否在 PATH 中，或使用绝对路径 `/usr/local/bin/uv`。
`Error: No Python version matches`	镜像目录中的 Release Tag 子目录名与下载的包不匹配。确保子目录名（如 `20250409`）与包文件名中的 Tag 一致。
`file://` 路径无法访问	确认路径是绝对路径，且 `file://` 协议格式正确（如 `file:///opt/offline/uv-python-mirror`）。
安装第三方包时报错	确认 `offline-packages` 目录中已包含所有依赖的 `.whl` 或 `.tar.gz` 文件，包括传递依赖。
需要多个 Python 版本	在准备阶段下载多个版本的 `tar.gz` 文件，放入同一个 Release Tag 子目录下，`uv python install` 时会自动识别。