跳转至

pyenv 使用

一、pyenv 简介

pyenv 是一个轻量级 Python 版本管理工具，可以：

  • ✅ 安装多个 Python 版本
  • ✅ 全局/局部切换版本
  • ✅ 配合 virtualenv 创建虚拟环境
  • ✅ 进入目录自动切换环境

适用场景： Web 开发、爬虫、脚本、多项目并行

二、安装步骤

2.1 Ubuntu / Debian 系

方法 A：官方脚本（需要访问 GitHub）

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# 安装编译依赖
sudo apt update

sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev \
  git wget

# 安装 pyenv（需要访问 GitHub）
curl -sSL https://pyenv.run | bash

# 配置 ~/.bashrc
cat >> ~/.bashrc << 'EOF'
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
EOF

source ~/.bashrc

方法 B：Gitee 镜像（国内推荐）

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 安装编译依赖
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev \
  git wget

# 从 Gitee 克隆 pyenv（主仓库）
git clone https://gitee.com/mirrors/pyenv.git ~/.pyenv

# 克隆 pyenv-virtualenv（GitHub，文件小一般可访问）
git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

# 如果 GitHub 超时，使用加速代理
git clone https://ghproxy.com/https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

# 配置 ~/.bashrc
cat >> ~/.bashrc << 'EOF'
export PYENV_ROOT="$HOME/.pyenv"
[ -d "$PYENV_ROOT/bin" ] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
EOF

source ~/.bashrc

2.2 RockyLinux / CentOS 系

方法 A：官方脚本（需要访问 GitHub）

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 安装编译依赖（RockyLinux 9 / CentOS 7.9）
sudo dnf groupinstall -y "Development Tools"
# 或 CentOS 7: sudo yum groupinstall -y "Development Tools"

sudo dnf install -y openssl-devel bzip2-devel libffi-devel zlib-devel \
  readline-devel sqlite-devel xz-devel tk-devel git wget curl

# CentOS 7 额外依赖
sudo yum install -y gcc libssl-dev

# 安装 pyenv（需要访问 GitHub）
curl -sSL https://pyenv.run | bash

# 配置 ~/.bashrc
cat >> ~/.bashrc << 'EOF'
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
EOF

source ~/.bashrc

方法 B：Gitee 镜像（国内推荐）

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 安装编译依赖
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y openssl-devel bzip2-devel libffi-devel zlib-devel \
  readline-devel sqlite-devel xz-devel tk-devel git wget curl

# 从 Gitee 克隆 pyenv（主仓库）
git clone https://gitee.com/mirrors/pyenv.git ~/.pyenv

# 克隆 pyenv-virtualenv（GitHub，文件小一般可访问）
git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

# 如果 GitHub 超时，使用加速代理
git clone https://ghproxy.com/https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

# 配置 ~/.bashrc
cat >> ~/.bashrc << 'EOF'
export PYENV_ROOT="$HOME/.pyenv"
[ -d "$PYENV_ROOT/bin" ] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
EOF

source ~/.bashrc

2.3 macOS

方法 A：Homebrew（推荐）

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# 安装 Homebrew（如果没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew update
brew install openssl readline sqlite3 xz zlib tcl-tk git

# 安装 pyenv
brew install pyenv pyenv-virtualenv

# 配置 ~/.zshrc（macOS 默认 zsh）
cat >> ~/.zshrc << 'EOF'
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
EOF

source ~/.zshrc

方法 B：Gitee 镜像

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# 安装依赖（需要 Homebrew）
brew install openssl readline sqlite3 xz zlib tcl-tk git

# 从 Gitee 克隆 pyenv（主仓库）
git clone https://gitee.com/mirrors/pyenv.git ~/.pyenv

# 克隆 pyenv-virtualenv（GitHub，文件小一般可访问）
git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

# 如果 GitHub 超时，使用加速代理
git clone https://ghproxy.com/https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

# 配置 ~/.zshrc
cat >> ~/.zshrc << 'EOF'
export PYENV_ROOT="$HOME/.pyenv"
[ -d "$PYENV_ROOT/bin" ] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
EOF

source ~/.zshrc

2.4 验证安装

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 所有平台通用
pyenv --version
# 输出：pyenv 1.x.x

pyenv commands
# 输出：所有可用命令列表

which pyenv
# 输出：~/.pyenv/bin/pyenv

# 检查插件
ls ~/.pyenv/plugins/
# 应包含：pyenv-virtualenv

2.5 网络问题解决方案

问题 解决方案
raw.githubusercontent.com 无法访问 使用 Gitee 镜像克隆 pyenv 主仓库
pyenv-virtualenv 克隆失败 直接用 GitHub 地址（文件小）或 ghproxy 加速
git clone 超时 使用 ghproxy.com 或 mirror.ghproxy.com 加速
Python 下载慢 设置 PYTHON_BUILD_MIRROR_URL 环境变量
pip 安装包慢 配置清华/阿里镜像源

国内用户推荐方案：

  1. pyenv 主仓库 → Gitee 镜像
  2. pyenv-virtualenv → GitHub 直连 或 ghproxy 加速

加速代理地址：

  • https://ghproxy.com/https://github.com/...
  • https://mirror.ghproxy.com/https://github.com/...

三、核心命令速查

3.1 版本管理

命令 说明
pyenv install --list 查看可安装版本
pyenv install 3.11.7 安装指定版本
pyenv uninstall 3.11.7 卸载版本
pyenv versions 查看所有已安装版本
pyenv version 查看当前使用版本
pyenv global 3.11.7 设置全局默认版本
pyenv local 3.11.7 设置当前目录版本
pyenv shell 3.11.7 临时切换版本（当前终端）
pyenv rehash 刷新命令缓存

3.2 虚拟环境管理

命令 说明
pyenv virtualenv 3.11.7 myenv 基于版本创建环境
pyenv virtualenvs 查看所有虚拟环境
pyenv activate myenv 激活环境
pyenv deactivate 退出环境
pyenv virtualenv-delete myenv 删除环境

四、实战场景

场景 1：多项目并行开发

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 1. 安装多个 Python 版本
pyenv install 3.9.18
pyenv install 3.10.13
pyenv install 3.11.7

# 2. 为每个项目创建环境
pyenv virtualenv 3.11.7 crawler-env
pyenv virtualenv 3.10.13 web-env
pyenv virtualenv 3.9.18 legacy-env

# 3. 项目 A - 爬虫项目
cd ~/projects/crawler
pyenv local crawler-env
# 自动生成 .python-version 文件
pip install requests beautifulsoup4 selenium

# 4. 项目 B - Web 项目
cd ~/projects/web-app
pyenv local web-env
pip install flask gunicorn

# 5. 项目 C - 旧系统
cd ~/projects/legacy
pyenv local legacy-env
pip install django==3.2

效果： 进入不同目录，Python 版本自动切换

场景 2：临时测试新版本

Bash
1
2
3
4
5
6
7
8
9
# 安装 Python 3.12 测试
pyenv install 3.12.1

# 临时切换到 3.12（仅当前终端）
pyenv shell 3.12.1
python --version  # Python 3.12.1

# 退出临时切换
pyenv shell --unset

场景 3：全局默认版本

Bash
1
2
3
4
5
# 设置全局默认 Python 3.11
pyenv global 3.11.7

# 验证
python --version  # Python 3.11.7

场景 4：查看版本信息

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 当前激活版本
pyenv version
# 输出：3.11.7 (set by /home/user/.pyenv/version)

# 所有版本（* 标记当前）
pyenv versions
# 输出：
#   3.9.18
#   3.10.13
# * 3.11.7 (set by /home/user/.pyenv/version)
#   crawler-env
#   web-env

五、项目结构示例

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
~/projects/
├── crawler/
│   ├── .python-version    # 内容：crawler-env
│   ├── .venv/             # 虚拟环境（pyenv 管理）
│   ├── src/
│   └── requirements.txt
│
├── web-app/
│   ├── .python-version    # 内容：web-env
│   ├── .venv/
│   ├── app.py
│   └── requirements.txt
│
└── legacy/
    ├── .python-version    # 内容：legacy-env
    ├── manage.py
    └── requirements.txt

.python-version 文件：

  • pyenv 自动读取此文件
  • 进入目录时自动激活对应环境
  • 无需手动执行 pyenv activate

六、常用工作流

6.1 新项目初始化

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

# 2. 选择 Python 版本并创建环境
pyenv virtualenv 3.11.7 my-project-env

# 3. 绑定到当前目录
pyenv local my-project-env

# 4. 验证
pyenv version  # 输出：my-project-env

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

6.2 迁移旧项目

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 1. 进入现有项目
cd /path/to/existing-project

# 2. 创建环境
pyenv virtualenv 3.10.13 existing-env

# 3. 绑定
pyenv local existing-env

# 4. 重新安装依赖
pip install -r requirements.txt

6.3 环境备份与恢复

Bash
1
2
3
4
5
6
7
# 导出依赖
pip freeze > requirements.txt

# 新环境恢复
pyenv virtualenv 3.11.7 new-env
pyenv local new-env
pip install -r requirements.txt

七、常见问题

Q1: 安装失败 - 编译错误

Bash
1
2
3
4
5
6
7
# 清理缓存重试
pyenv uninstall 3.11.7
rm -rf ~/.pyenv/cache/
pyenv install 3.11.7

# 检查依赖
sudo apt install build-essential libssl-dev

Q2: 命令找不到

Bash
1
2
3
4
5
# 刷新缓存
pyenv rehash

# 检查 PATH
echo $PATH | grep pyenv

Q3: 环境不自动切换

Bash
1
2
3
4
5
6
# 检查 .python-version 文件
cat .python-version

# 重新绑定
pyenv local --unset
pyenv local <env-name>

Q4: pip 安装包慢

Bash
1
2
3
4
5
# 使用国内镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package>

# 永久配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

八、最佳实践

✅ 推荐做法

  1. 每个项目独立环境 - 避免依赖冲突
  2. 使用 .python-version - 自动切换，团队协作一致
  3. 固定 requirements.txt - pip freeze > requirements.txt
  4. 定期清理旧版本 - pyenv uninstall <version>

❌ 避免做法

  1. 不要在全局环境安装包
  2. 不要手动修改 .pyenv 目录
  3. 不要混用 pyenv 和系统 Python
  4. 不要删除 .python-version 文件（除非不再需要）

九、快捷别名（可选）

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 添加到 ~/.bashrc
cat >> ~/.bashrc << 'EOF'

# pyenv 快捷命令
alias pyv='pyenv version'
alias pyvs='pyenv versions'
alias pyi='pyenv install'
alias pyu='pyenv uninstall'
alias pya='pyenv activate'
alias pyd='pyenv deactivate'
EOF

source ~/.bashrc

十、参考资料