概述

Pyenv 是一个强大的 Python 版本管理工具，允许在同一系统中安装和切换多个 Python 版本，而不影响系统自带的 Python。

核心功能：

  • 🔧 多版本 Python 共存
  • 🔄 灵活的版本切换机制
  • 📦 简单的安装和管理
  • 🎯 项目级版本隔离

适用场景：

  • 不同项目需要不同 Python 版本
  • 测试代码在多个 Python 版本的兼容性
  • 避免影响系统自带 Python
  • 开发环境与生产环境版本匹配

安装 Pyenv

一键安装

1
curl https://pyenv.run | bash

安装内容：

  • pyenv：核心工具
  • pyenv-virtualenv：虚拟环境插件
  • pyenv-update：更新插件
  • pyenv-doctor：诊断插件

配置环境变量

Zsh 用户（~/.zshrc）：

1
2
3
4
5
6
7
8
9
10
# Pyenv 配置
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

# 初始化 pyenv
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

# 可选：启用 pyenv-virtualenv
eval "$(pyenv virtualenv-init -)"

Bash 用户（~/.bashrc 或 ~/.bash_profile）：

1
2
3
4
5
# Pyenv 配置
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

应用配置：

1
2
3
4
5
# Zsh
source ~/.zshrc

# Bash
source ~/.bashrc  # 或 source ~/.bash_profile

验证安装

1
2
3
4
# 检查 pyenv 版本
pyenv --version

# 输出示例：pyenv 2.3.x

基础命令

查看版本

当前激活版本：

1
2
3
4
pyenv version

# 输出示例：
# 3.10.16 (set by /Users/username/.pyenv/version)

已安装的所有版本：

1
2
3
4
5
6
7
pyenv versions

# 输出示例：
#   system
# * 3.10.16 (set by /Users/username/.pyenv/version)
#   3.11.5
#   3.12.0

说明：

  • system：系统自带的 Python
  • *：当前激活的版本

列出可安装版本

查看所有可用版本：

1
2
3
4
pyenv install --list

# 或简写
pyenv install -l

过滤特定版本：

1
2
3
4
5
# 查看所有 3.11.x 版本
pyenv install --list | grep " 3\.11\."

# 查看所有 3.x 版本
pyenv install --list | grep " 3\."

安装 Python 版本

安装指定版本

1
2
3
4
5
6
7
8
# 安装 Python 3.10.16
pyenv install 3.10.16

# 安装 Python 3.11.5
pyenv install 3.11.5

# 安装 Python 3.12.0
pyenv install 3.12.0

重建 shims

每次安装后必须执行：

1
pyenv rehash

rehash 的作用：

  • 重新生成 shims（垫片）
  • 确保新安装的 Python 可被识别
  • 更新命令路径映射

加速安装（可选）

使用国内镜像：

1
2
3
4
5
6
7
# 临时使用淘宝镜像
PYTHON_BUILD_MIRROR_URL="https://npm.taobao.org/mirrors/python/" \
  pyenv install 3.10.16

# 或设置环境变量（永久生效）
export PYTHON_BUILD_MIRROR_URL="https://npm.taobao.org/mirrors/python/"
pyenv install 3.10.16

版本切换

三种切换方式

Pyenv 提供三种版本切换方式，优先级从高到低：shell > local > global

Global（全局）

作用域： 所有目录的默认版本

1
2
3
4
5
# 设置全局版本
pyenv global 3.10.16

# 查看当前全局版本
pyenv global

配置文件： ~/.pyenv/version

建议：

⚠️ 不建议改变系统全局版本，保持 system 较安全

Local（项目级）

作用域： 当前目录及其子目录

1
2
3
4
5
6
7
8
# 进入项目目录
cd ~/projects/myapp

# 设置项目专用版本
pyenv local 3.11.5

# 查看当前目录版本
pyenv local

配置文件： 当前目录的 .python-version

取消设置：

1
2
3
4
pyenv local --unset

# 或直接删除配置文件
rm .python-version

使用场景：

  • ✅ 推荐：为不同项目指定不同 Python 版本
  • ✅ 团队协作：提交 .python-version 到版本控制
  • ✅ 自动切换：进入项目目录自动激活对应版本

Shell（会话级）

作用域： 当前 shell 会话

1
2
3
4
5
6
7
8
# 临时切换版本
pyenv shell 3.12.0

# 查看当前 shell 版本
pyenv shell

# 取消设置
pyenv shell --unset

特点：

  • 仅在当前终端窗口生效
  • 关闭终端后失效
  • 适合临时测试

版本优先级

优先级顺序（从高到低）：

1
shell（会话级） > local（项目级） > global（全局级） > system（系统级）

示例场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 1. 设置全局版本为 3.10.16
pyenv global 3.10.16

# 2. 项目 A 使用 3.11.5
cd ~/projects/project-a
pyenv local 3.11.5

# 3. 临时测试 3.12.0
pyenv shell 3.12.0

# 此时实际使用：3.12.0（shell 优先级最高）
python --version  # Python 3.12.0

# 取消 shell 设置
pyenv shell --unset

# 现在使用：3.11.5（local 生效）
python --version  # Python 3.11.5

# 离开项目目录
cd ~

# 现在使用：3.10.16（global 生效）
python --version  # Python 3.10.16

版本管理

卸载版本

1
2
3
4
5
# 卸载指定版本
pyenv uninstall 3.10.16

# 确认卸载
# 输入 y 确认

更新 Pyenv

1
2
3
4
5
6
# 使用 pyenv-update 插件
pyenv update

# 或手动更新
cd ~/.pyenv
git pull

查看 Python 路径

1
2
3
4
5
6
# 查看当前 Python 路径
pyenv which python

# 查看特定命令路径
pyenv which pip
pyenv which python3

常见问题

问题1：pyenv: version system not installed

错误信息：

1
pyenv: version `system` not installed

解决方案：

确保在 shell 配置文件中添加了初始化代码：

1
2
# ~/.zshrc 或 ~/.bashrc
eval "$(pyenv init -)"

然后重新加载配置：

1
source ~/.zshrc  # 或 source ~/.bashrc

问题2：安装失败

可能原因： 缺少编译依赖

macOS 解决方案：

1
2
3
4
5
# 安装 Xcode Command Line Tools
xcode-select --install

# 使用 Homebrew 安装依赖
brew install openssl readline sqlite3 xz zlib

Linux 解决方案：

1
2
3
4
5
6
7
8
9
10
11
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
  make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# CentOS/RHEL
sudo yum install -y \
  gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite \
  sqlite-devel openssl-devel xz xz-devel libffi-devel

问题3：命令找不到

症状： 安装后 pyenv 命令不可用

检查步骤：

  1. 确认 PATH 设置：
1
echo $PATH | grep pyenv
  1. 确认 pyenv 安装位置：
1
ls -la ~/.pyenv
  1. 重新添加环境变量并加载

卸载 Pyenv

方法一：保留配置

1
2
3
4
5
6
7
8
# 1. 移除 shell 启动项中的 pyenv 配置
# 编辑 ~/.zshrc 或 ~/.bashrc，删除 pyenv 相关行

# 2. 删除 pyenv 目录
rm -rf $(pyenv root)

# 或
rm -rf ~/.pyenv

方法二：完全卸载（Homebrew）

1
2
3
4
5
6
7
# 1. 移除 shell 配置

# 2. 卸载 pyenv
brew uninstall pyenv

# 3. 删除配置文件
rm -rf ~/.pyenv

最佳实践

推荐配置

项目结构：

1
2
3
4
5
my-project/
├── .python-version    # 项目指定 Python 版本
├── requirements.txt   # 依赖列表
├── venv/             # 虚拟环境（可选）
└── src/

工作流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 1. 创建项目
mkdir my-project && cd my-project

# 2. 设置 Python 版本
pyenv local 3.11.5

# 3. 创建虚拟环境
python -m venv venv

# 4. 激活虚拟环境
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

# 5. 安装依赖
pip install -r requirements.txt

常用命令速查

命令说明
pyenv versions查看已安装版本
pyenv install -l列出可安装版本
pyenv install 3.x.x安装指定版本
pyenv uninstall 3.x.x卸载指定版本
pyenv global 3.x.x设置全局版本
pyenv local 3.x.x设置项目版本
pyenv shell 3.x.x设置会话版本
pyenv rehash重建 shims
pyenv which python查看 Python 路径

版本选择建议

生产环境：

  • ✅ 使用稳定版本（如 3.10.x、3.11.x）
  • ✅ 避免使用 alpha/beta 版本
  • ✅ 与目标部署环境版本一致

开发环境：

  • ✅ 为每个项目设置 local 版本
  • ✅ 团队统一 Python 版本
  • ✅ 使用 .python-version 文件

学习测试：

  • ✅ 可以尝试最新版本
  • ✅ 使用 shell 临时切换
  • ✅ 不影响其他项目

总结

Pyenv 核心优势：

特性说明
✅ 多版本共存同时安装多个 Python 版本
✅ 灵活切换三级切换机制（shell/local/global）
✅ 项目隔离不同项目使用不同版本
✅ 简单管理命令简洁，易于使用

快速上手：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 安装 pyenv
curl https://pyenv.run | bash

# 配置环境变量（添加到 ~/.zshrc）
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

# 安装 Python
pyenv install 3.11.5

# 设置版本
pyenv global 3.11.5  # 或 pyenv local 3.11.5