Skip to main content

Pyenv 使用完整指南

Pyenv 是一个强大的 Python 版本管理工具，可以让你轻松安装、切换和管理多个 Python 版本。以下是详细使用指南：

1. 安装 Pyenv

Linux/macOS 安装

curl https://pyenv.run | bash

安装完成后，将以下内容添加到 shell 配置文件（如 ~/.bashrc, ~/.zshrc 或 ~/.bash_profile）：

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"  # 如果要用虚拟环境插件

然后重新加载 shell：

exec "$SHELL"

Windows 安装

Windows 用户可以使用 pyenv-win：

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

2. 基本命令

安装 Python 版本

# 查看可安装版本
pyenv install --list

# 安装特定版本
pyenv install 3.9.7

# 安装最新稳定版
pyenv install $(pyenv latest -k 3)

查看已安装版本

pyenv versions

带 * 的表示当前激活的版本。

切换 Python 版本

# 全局设置（影响整个系统）
pyenv global 3.9.7

# 局部设置（仅当前目录及其子目录）
pyenv local 3.8.12

# shell会话级别设置（仅当前终端）
pyenv shell 3.10.0

卸载 Python 版本

pyenv uninstall 3.7.12

3. 高级功能

虚拟环境管理

Pyenv 可以与 pyenv-virtualenv 插件配合使用：

# 创建虚拟环境
pyenv virtualenv 3.9.7 my-project-env

# 激活虚拟环境
pyenv activate my-project-env

# 停用虚拟环境
pyenv deactivate

# 删除虚拟环境
pyenv uninstall my-project-env

版本优先级

Pyenv 按以下顺序决定使用哪个 Python 版本：

  1. PYENV_VERSION 环境变量
  2. 当前目录的 .python-version 文件（由 pyenv local 创建）
  3. 第一个找到的父目录中的 .python-version 文件
  4. 全局版本（由 pyenv global 设置）

自定义构建选项

# 安装时启用优化
PYTHON_CONFIGURE_OPTS="--enable-optimizations" pyenv install 3.9.7

# 安装特定架构版本
env PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.10.0

4. 常见问题解决

安装失败（缺少依赖）

# Ubuntu/Debian
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 tk-devel libffi-devel

速度慢的解决方法

使用国内镜像：

# 临时使用镜像
v=3.9.7;wget https://npm.taobao.org/mirrors/python/$v/Python-$v.tar.xz -P ~/.pyenv/cache/;pyenv install $v

# 或设置环境变量
export PYTHON_BUILD_MIRROR_URL="https://npm.taobao.org/mirrors/python"

更新 Pyenv

pyenv update

5. 实际应用示例

项目中使用特定 Python 版本

# 进入项目目录
cd my-project

# 设置项目使用的Python版本
pyenv local 3.8.12

# 创建项目专用虚拟环境
pyenv virtualenv 3.8.12 my-project-env

# 激活环境
pyenv activate my-project-env

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

多版本切换演示

# 查看当前版本
python --version

# 切换到另一个版本
pyenv shell 3.7.12
python --version

# 切换回来
pyenv shell --unset
python --version

6. 配置建议

在 ~/.pyenv/ 目录下可以配置一些默认行为：

  • plugins/python-build/share/python-build/ - 可以添加自定义的 Python 版本定义
  • cache/ - 缓存下载的 Python 源码包

7. 与其他工具集成

与 Pipenv 配合使用

pyenv local 3.9.7
pip install --user pipenv
pipenv install

与 Poetry 配合使用

pyenv local 3.10.0
curl -sSL https://install.python-poetry.org | python -
poetry init

Pyenv 提供了灵活的 Python 版本管理，特别适合需要同时处理多个项目的开发者。

No Comments
Back to top