CentOS7 使用 uv 安装 Python3.11.9 生产部署文档

一、环境说明

操作系统：CentOS 7 (Core) 系统自带 Python：2.7.5（严禁删除 / 覆盖，yum 依赖此版本） glibc：2.17 方案：uv + python-build-standalone 预编译包优势：无需编译 gcc、无需编译 openssl，部署速度快，和系统 Python 完全隔离限制：预编译包为 Astral 官方提供，不是 Python 源码编译产物；自带 PEP-668 外部环境保护，禁止直接全局安装 pip 包，业务必须使用虚拟环境

二、安装 uv

bash 复制代码

# 执行uv官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh
# 加载环境变量
source $HOME/.local/bin/env
# 建立全局软链接，所有终端可直接调用uv
ln -sf /root/.local/bin/uv /usr/local/bin/uv
ln -sf /root/.local/bin/uvx /usr/local/bin/uvx
# 验证uv
uv --version

三、使用 uv 安装 Python 3.11.9

bash 复制代码

# 安装指定版本Python
uv python install 3.11.9
# 查看本地已管理的Python列表
uv python list

备注：执行 uv python list 出现关于 /usr/bin/python 的 warning，是系统 python2.7 不支持 uv 的检测参数，属于正常告警，不影响使用。

四、配置全局软链接（python3.11、pip3.11 全局调用）

bash 复制代码

# 获取3.11.9解释器路径
PY311_PATH=$(uv python find 3.11.9)
echo $PY311_PATH
# 创建软链接
ln -sf $PY311_PATH /usr/local/bin/python3.11
ln -sf $(dirname $PY311_PATH)/pip3.11 /usr/local/bin/pip3.11
# 版本校验
python3.11 --version
pip3.11 --version
# 校验ssl模块（生产必检，确认pip可正常访问https源）
python3.11 -c "import ssl; print(ssl.OPENSSL_VERSION)"

五、全局环境变量持久化（新开终端自动识别 uv）

bash 复制代码

cat > /etc/profile.d/uv.sh <<'EOF'
export PATH="/root/.local/bin:$PATH"
EOF
chmod +x /etc/profile.d/uv.sh
source /etc/profile.d/uv.sh

六、配置国内清华 PyPI 源（生产加速，可选）

bash 复制代码

mkdir -p /root/.config/uv
cat > /root/.config/uv/uv.toml <<'EOF'
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
EOF

七、业务使用规范（生产重点）

禁止直接执行 pip3.11 install xxx，会抛出 externally-managed-environment 报错

1、创建虚拟环境

bash 复制代码

# 进入业务目录
cd /opt/myapp
# 基于3.11.9创建虚拟环境
uv venv --python 3.11.9 .venv
# 激活虚拟环境
source .venv/bin/activate
# 在虚拟环境内安装依赖
uv pip install 包名

2、退出虚拟环境

bash 复制代码

deactivate

八、卸载方案（清理干净）

bash 复制代码

# 卸载uv管理的python3.11.9
uv python uninstall 3.11.9
# 删除软链接
rm -f /usr/local/bin/python3.11
rm -f /usr/local/bin/pip3.11
rm -f /usr/local/bin/uv
rm -f /usr/local/bin/uvx
# 删除uv程序、环境配置
rm -rf /root/.local/bin/uv /root/.local/bin/uvx
rm -f /etc/profile.d/uv.sh
rm -rf /root/.local/share/uv

九、常见问题

uv python install 下载超时：配置镜像环境变量后再执行

bash 复制代码

export UV_PYTHON_INSTALL_MIRROR=https://ghproxy.com/https://github.com/astral-sh/python-build-standalone/releases/download
uv python install 3.11.9

报错 externally-managed-environment：没有使用虚拟环境，业务代码必须放到 uv venv 环境中运行
新开终端 uv 命令找不到：确认 /etc/profile.d/uv.sh 文件存在，并且已经 source 生效

十、生产小结

不污染系统自带 Python2.7，yum 安全不受影响
部署快，规避 CentOS7 gcc、openssl、glibc 编译一系列坑
所有业务代码、依赖包隔离在独立虚拟环境，版本隔离，方便回滚
审计要求必须官方源码编译 Python 的场景，该方案不可用