跳转到主要内容

​
Pyenv

Pyenv 是一个 Python 版本管理工具，允许你在同一系统上轻松安装和切换多个 Python 版本。

​
特性

  • 📦 管理多个 Python 版本
  • 🔄 快速切换 Python 版本
  • 🎯 为项目设置特定版本
  • 🌐 支持虚拟环境
  • 🪟 跨平台支持（Windows/Linux/Mac）

​
安装

​
Windows

使用 pyenv-win： 
# 使用 pip 安装
pip install pyenv-win --target $HOME/.pyenv

# 或使用 Git
git clone https://github.com/pyenv-win/pyenv-win.git $HOME/.pyenv
添加环境变量： 
[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

​
Linux/Mac

# 使用官方安装脚本
curl https://pyenv.run | bash

# 或使用 Homebrew (Mac)
brew install pyenv
配置 Shell（添加到 ~/.bashrc 或 ~/.zshrc）： 
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

​
基本使用

​
查看可安装的版本

# 列出所有可用版本
pyenv install --list

# 搜索特定版本
pyenv install --list | grep 3.11

​
安装 Python 版本

# 安装特定版本
pyenv install 3.11.5

# 安装最新版本
pyenv install 3.11

# 查看安装进度
pyenv install -v 3.11.5

​
查看已安装版本

# 列出所有已安装版本
pyenv versions

# 查看当前版本
pyenv version

​
切换 Python 版本

# 全局切换（所有 shell）
pyenv global 3.11.5

# 本地切换（当前目录）
pyenv local 3.10.12

# 临时切换（当前 shell）
pyenv shell 3.9.18

​
卸载版本

pyenv uninstall 3.9.18

​
高级用法

​
为项目设置版本

# 在项目目录下
cd my_project
pyenv local 3.11.5

# 会创建 .python-version 文件
cat .python-version
# 3.11.5

​
虚拟环境

结合 pyenv-virtualenv 使用： 
# 安装 pyenv-virtualenv
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

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

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

# 停用虚拟环境
pyenv deactivate

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

# 为项目自动激活虚拟环境
cd my_project
pyenv local my-project-env

​
查看版本来源

# 查看当前版本及来源
pyenv version
# 3.11.5 (set by /home/user/project/.python-version)

​
刷新 shims

# 重新生成 shims（安装新包后）
pyenv rehash

​
配置文件

​
全局配置

# 设置全局版本
pyenv global 3.11.5

# 配置文件位置
~/.pyenv/version

​
项目配置

# 项目目录下的 .python-version 文件
echo "3.11.5" > .python-version

​
Shell 配置

# 临时设置
export PYENV_VERSION=3.11.5

​
常见问题

​
安装失败

Linux 依赖缺失： 
# Ubuntu/Debian
sudo apt update
sudo apt 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 gcc zlib-devel bzip2 bzip2-devel readline-devel \
  sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel

​
版本切换不生效

# 确保 pyenv 在 PATH 中
which pyenv

# 重新加载配置
source ~/.bashrc  # 或 ~/.zshrc

# 重新生成 shims
pyenv rehash

​
Windows 路径问题

确保环境变量配置正确，并重启终端。

​
与其他工具对比

工具特点适用场景
pyenv多版本管理需要频繁切换 Python 版本
venv内置虚拟环境简单项目隔离
conda科学计算环境数据科学、机器学习
poetry依赖管理 + 打包现代 Python 项目
pipenvPipfile 管理依赖锁定

​
最佳实践

  1. 为每个项目设置 local 版本：避免全局版本冲突
  2. 使用虚拟环境：结合 pyenv-virtualenv
  3. 提交 .python-version：团队协作时统一版本
  4. 定期更新 pyenv：获取新版本支持
  5. 记录依赖：使用 requirements.txt 或 Pipfile

​
实用命令总结

# 常用命令速查
pyenv install --list          # 查看可安装版本
pyenv install 3.11.5          # 安装版本
pyenv versions                # 查看已安装版本
pyenv global 3.11.5           # 全局切换
pyenv local 3.11.5            # 项目切换
pyenv uninstall 3.11.5        # 卸载版本
pyenv rehash                  # 刷新 shims
pyenv which python            # 查看 python 路径

​
参考资源

最后修改于 2026年4月19日