离线 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绝大多数 CentOSuv-x86_64-unknown-linux-gnu.tar.gzARM64 (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.12cpython-3.12.1020250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz多版本准备如果需要在离线机器上安装多个 Python 版本请一并下载对应的tar.gz文件。2.3 组织本地目录结构关键步骤uv从镜像源读取 Python 安装包时需要特定的目录结构。下载的tar.gz文件需要按照 Release Tag 放入对应的子目录中。在联网机器上创建如下目录结构# 创建镜像根目录mkdir-p~/uv-python-mirror/# 创建以 Release Tag 命名的子目录以 20250409 为例mkdir-p~/uv-python-mirror/20250409/# 将下载的 Python tar.gz 文件移入该子目录mvcpython-*.tar.gz ~/uv-python-mirror/20250409/目录结构示例~/uv-python-mirror/ └── 20250409/ ├── cpython-3.10.1720250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz ├── cpython-3.11.1220250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz └── cpython-3.12.1020250409-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.gzuv 二进制包uv-python-mirror/整个目录Python 预编译包镜像四、安装阶段在离线 CentOS 服务器上操作4.1 安装 uv 工具# 1. 进入存放安装包的目录cd/opt/offline/# 2. 解压 uv 二进制包tar-xzvfuv-x86_64-unknown-linux-gnu.tar.gz# 3. 将 uv 和 uvx 移动到系统 PATH 路径需要 root 权限sudomvuv uvx /usr/local/bin/# 4. 验证安装uv--version# 应输出类似uv 0.x.x4.2 配置 Python 安装镜像源将uv的 Python 下载源指向本地镜像目录。有两种方式方式一通过环境变量推荐全局生效# 临时生效当前终端会话exportUV_PYTHON_INSTALL_MIRRORfile:///opt/offline/uv-python-mirror# 永久生效写入 ~/.bashrcechoexport UV_PYTHON_INSTALL_MIRRORfile:///opt/offline/uv-python-mirror~/.bashrcsource~/.bashrc方式二通过命令行参数临时指定uv pythoninstall--mirrorfile:///opt/offline/uv-python-mirror3.12注意file://协议后面跟的是镜像根目录的绝对路径不是子目录路径。4.3 使用 uv 安装 Python配置好镜像源后即可像在线环境一样使用uv python install命令安装 Python# 安装指定版本的 Python精确版本号uv pythoninstall3.12.10# 或安装主版本号uv 会自动匹配最新的补丁版本uv pythoninstall3.12uv会自动从file:///opt/offline/uv-python-mirror目录下查找与 Release Tag 匹配的子目录并在其中寻找对应版本的tar.gz文件进行安装。4.4 验证 Python 安装# 查看已安装的 Python 版本列表uv python list# 使用新安装的 Python 创建虚拟环境uv venv--python3.12.venv# 激活虚拟环境source.venv/bin/activate# 验证 Python 版本python--version# 应输出Python 3.12.10五、离线安装 Python 第三方包扩展在离线环境中除了安装 Python 解释器通常还需要安装第三方依赖包。核心思路是在联网机器上预先下载好所有依赖包然后拷贝到离线机器安装。5.1 在联网机器上下载依赖包# 1. 创建依赖清单echonumpy pandas requestsrequirements.txt# 2. 使用 uv 下载所有依赖包到本地目录uv pip download-d./offline-packages-rrequirements.txt5.2 传输到离线机器并安装# 将 offline-packages 目录拷贝到离线机器后执行# 激活虚拟环境source.venv/bin/activate# 从本地目录安装所有依赖uv pipinstall--no-index --find-links ./offline-packages-rrequirements.txt参数说明--no-index禁止访问 PyPI 网络索引--find-links指定从本地目录查找包文件六、常见问题与排查问题现象可能原因及解决办法uv: command not founduv未添加到 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时会自动识别。
