Ubuntu 安装 pyenv 管理多个 Python 版本（含 uv 对比）

一、痛点：你一定遇到过这些场景

痛点	描述
系统 Python 不敢动	改了系统自带 Python 版本，yum/apt 直接挂掉
多项目多版本	项目 A 要 3.9，项目 B 要 3.12，切来切去头大
装不上指定版本	源码编译一堆依赖缺失，半天才搞定
版本切换靠改名	python3.9、python3.12 一堆别名，自己都记不住

如果你中了一条以上，pyenv 就是你需要的工具。

二、pyenv 是什么？

pyenv 是一个轻量级的 Python 版本管理器，让你在同一台机器上：

• 安装任意版本的 Python（2.x、3.x、Anaconda、PyPy 等）
• 按目录/全局切换版本，无需修改系统 Python
• 不依赖 Python 本身，纯 Shell 实现，零侵入

核心原理：通过 PATH 劫持，拦截 python 命令，指向你指定的版本。干净、可逆、安全。

三、一张图看懂 pyenv 版本切换

~/project-a/  →  .python-version = 3.9.21  →  python → 3.9.21
~/project-b/  →  .python-version = 3.14.4  →  python → 3.14.4
全局           →  pyenv global 3.14.4       →  python → 3.14.4

四、一键安装 pyenv（Ubuntu/Debian）

脚本会自动检测缺失的依赖库，只安装缺失的部分：

#!/bin/bash
set -euo pipefail

# pyenv 一键安装脚本 (自动检测缺失依赖)
# 用法: bash install-pyenv.sh

echo "=== [1/5] 安装 pyenv ==="
curl https://pyenv.run | bash

echo "=== [2/5] 配置 Shell 环境 ==="
SHELL_RC="${HOME}/.$(basename "${SHELL}")rc"
grep -q 'pyenv' "${SHELL_RC}" 2>/dev/null || {
  cat >> "${SHELL_RC}" << 'PYENV_INIT'

# >>> pyenv >>>
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
# <<< pyenv <<<
PYENV_INIT
  echo "已写入 ${SHELL_RC}"
}

echo "=== [3/5] 检测并安装编译依赖 ==="
REQUIRED_PKGS=(
  libffi-dev
  libreadline-dev
  libssl-dev
  zlib1g-dev
  libbz2-dev
  libsqlite3-dev
  liblzma-dev
)

MISSING_PKGS=()
for pkg in "${REQUIRED_PKGS[@]}"; do
  if ! dpkg -s "$pkg" &>/dev/null; then
    MISSING_PKGS+=("$pkg")
  fi
done

if [ ${#MISSING_PKGS[@]} -eq 0 ]; then
  echo "所有依赖已安装。"
else
  echo "缺少以下依赖："
  printf '  - %s\n' "${MISSING_PKGS[@]}"
  sudo apt install -y "${MISSING_PKGS[@]}"
  echo "依赖安装完成。"
fi

echo "=== [4/5] 激活环境 ==="
# shellcheck source=/dev/null
source "${SHELL_RC}" 2>/dev/null || true
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

echo "=== [5/5] 验证 ==="
if command -v pyenv &>/dev/null; then
  echo "pyenv $(pyenv --version) 安装成功！"
else
  echo "pyenv 未找到，请重新打开终端"
fi

echo ""
echo "========================================="
echo " 下一步："
echo " 1. pyenv install 3.14.4"
echo " 2. pyenv global 3.14.4"
echo " 3. python -V"
echo "========================================="

注意：必须在编译 Python 之前装好 -dev 库，否则 bz2、sqlite3、lzma 等模块不会被编译。这是最常见的坑。

五、日常使用速查

安装指定版本

pyenv install --list | grep "3.14"   # 查看可安装版本
pyenv install 3.14.4                  # 安装 Python 3.14.4
pyenv install 3.12.10                 # 安装 Python 3.12.10
pyenv install 3.13.5                  # 安装 Python 3.13.5

切换版本

pyenv global 3.14.4   # 全局切换（所有目录生效）
pyenv local 3.9.21    # 当前目录切换（只影响当前项目）
pyenv shell 3.12.9    # 当前 Shell 临时切换

版本优先级

PYENV_VERSION 环境变量  >  .python-version（local）  >  global  >  系统 Python

其他命令

pyenv versions          # 查看已安装版本
pyenv uninstall 3.9.21  # 卸载指定版本
pyenv prefix 3.14.4     # 查看安装路径

六、pyenv + virtualenv：版本管理 + 虚拟环境

pyenv 管理版本，virtualenv/venv 管理包隔离，搭配使用最佳：

# 安装 pyenv-virtualenv 插件（curl 安装 pyenv 时已自动包含）
# 创建虚拟环境
pyenv virtualenv 3.14.4 myproject-env

# 在项目目录绑定虚拟环境
cd ~/myproject
pyenv local myproject-env

# 现在进入目录自动激活，离开自动 deactivate
pip install flask requests  # 隔离安装，不影响其他项目

也可以直接用 Python 自带 venv：

pyenv global 3.14.4
python -m venv .venv
source .venv/bin/activate

七、为什么选 pyenv？对比 uv / conda / Docker

特性	pyenv	uv	conda	Docker
多版本共存	✅	✅	✅	✅
按目录切换	✅	❌	❌	❌
不改系统 Python	✅	✅	✅	✅
安装任意版本	✅	✅	有限	✅
轻量	✅	✅	❌	❌
学习成本	低	低	中	高
安装速度	中（编译）	快（预编译）	中	慢
包管理	❌（需配合 pip/venv）	✅（内置）	✅	需手动
离线可用	❌	✅	✅	✅

选 pyenv 的场景：需要按目录自动切换 Python 版本、已熟悉 pip/venv 工作流
选 uv 的场景：追求极致速度、需要版本+包管理一体化
选 conda 的场景：需要科学计算生态（NumPy/Pandas 预编译包）

八、常见问题 FAQ

安装 Python 后报 ModuleNotFoundError

ModuleNotFoundError: No module named '_bz2'、No module named '_sqlite3'、No module named '_lzma' 是 pyenv 用户最常遇到的问题。

原因：编译 Python 前缺少开发库。解决方案：

sudo apt install -y libbz2-dev libsqlite3-dev liblzma-dev
pyenv uninstall 3.14.4
pyenv install 3.14.4

pyenv: command not found

没有加载 Shell 初始化，执行 source ~/.bashrc 或重新打开终端。

编译太慢怎么办

CONFIGURE_OPTS="--enable-optimizations" pyenv install 3.14.4

Python 3.12 / 3.13 / 3.14 安装有什么区别

Python 3.12+ 编译依赖基本相同，上述依赖库一次性装好即可支持所有版本。3.13 新增 free-threaded 模式（实验性），3.14 是当前最新开发版。

九、谁适合用 pyenv？

• 同时维护多个 Python 项目的开发者
• 需要测试代码在不同 Python 版本下兼容性的人
• 不想动系统 Python 的 Ubuntu/Linux 用户
• 从源码编译 Python 总是踩坑的人
• 需要按目录自动切换 Python 版本的团队

十、总结

pyenv 用最简单的方式解决了 Python 版本管理的核心问题：装得快、切得快、不影响系统。一行命令装版本，一行命令切版本，再也不用在 Python 版本之间手忙脚乱。