前言

Python 版本管理工具的主要作用是帮助开发者在同一台机器上管理多个 Python 版本和环境。pyenv具有以下功能：

1. 多版本并存

• 除了切换 Python 版本，Pyenv 还能同时安装多个版本（如 3.7, 3.9, 3.11），方便调试兼容性问题。例如：某些老项目只能在 Python 3.7 跑，而新项目需要 3.11，Pyenv 能很好地支持。

2. 灵活的版本切换机制，Pyenv 提供三种切换方式，这让不同项目之间能自动使用各自需要的 Python 版本，而无需人工切换。

• 全局版本（pyenv global）：整台机器的默认 Python 版本。
• 本地版本（pyenv local）：某个项目目录下的 Python 版本，写入 .python-version 文件。
• 临时版本（pyenv shell）：仅在当前 shell 会话有效。

3. 与虚拟环境集成，Pyenv 可以配合 pyenv-virtualenv 插件，方便管理虚拟环境：

• 可以给不同项目创建独立的虚拟环境
• 可以基于不同 Python 版本创建隔离环境
• 自动激活/切换项目环境

4. 与系统环境隔离

• 避免破坏系统自带的 Python（Linux/Mac 常用于系统工具）。
• 在用户目录安装，无须 root 权限，对开发者非常友好。

5. 插件生态，Pyenv 有丰富的插件生态，比如：

• pyenv-virtualenv → 虚拟环境管理
• pyenv-update → 一键更新 pyenv
• pyenv-doctor → 检查环境是否正确
• pyenv-which-ext → 查看命令在哪个环境中

6. CI/CD 与团队协作

• .python-version 文件可提交到项目仓库，保证团队统一 Python 版本。
• 在 CI/CD 中（如 GitHub Actions、GitLab CI）配合 pyenv，确保测试和生产使用一致的 Python 版本。

Pyenv 安装

1. Mac系统下的Pyenv工具的安装与配置

1. 更新 homebrew 并安装 pyenv：

zsh
brew update
brew install pyenv

2. 通过在终端中运行以下命令将 Pyenv 启动命令添加到 ~/.zshrc：

zsh
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

3. Pyenv 基本用法

zsh
## 查看帮助文档
pyenv

## 查看某个命令帮助文档
pyenv install --help

## 查看版本
pyenv version

## 检查 Python 是否正常运行
python -c "import sys; print(sys.executable)"

## 查看已安装的 Python 版本
pyenv versions

## 查看当前使用的 Python 版本
pyenv version

## 查看所有可用的 Python 版
pyenv install --list 

## 安装指定版本
pyenv install 3.9.1

## 安装指定版本，并输出安装日志
pyenv install -v 3.9.1 

## 验证
python --version

## 输出当前正在使用的 Python 是 安装在什么路径下（将输出路径复制进pycharm的项目解释器中即可）。
pyenv prefix

## 卸载指定版本
pyenv uninstall 3.9.1

## 全局指定 Python 版本（影响所有项目）
pyenv global 3.9.1 
## 恢复系统解释器
pyenv global system

## 局部指定 Python 版本（仅影响当前项目目录），指定后在当前项目目录内创建 .python-version 文件，保存版本信息
## 优先级高于 global(常跟source ~/.zshrc搭配，将~/.zshrc文件里的内容“直接加载”到当前会话)
pyenv local 3.9.1
# 撤销pyenv local影响
pyenv local --unset

## 会话级指定 Python 版本（影响所有项目）
pyenv shell 3.9.1 

## 查看 python 的安装目录
pyenv which python
## 查看系统版本
pyenv which python3.11.1

## 重新生成 pyenv 的 shims 目录中的可执行文件
pyenv rehash

4. pyenv install XX 经常超时问题解决,这个在国内环境里非常常见，尤其是 Python 官方源速度比较慢.

zsh
## 打开终端，编辑 zsh 配置
nano ~/.zshrc

## 将以下配置内容复制进去
export PYTHON_BUILD_MIRROR_URL="https://mirrors.huaweicloud.com/python"
export PYTHON_BUILD_MIRROR_URL_SKIP_CHECKSUM=1

## 生效配置文件
source ~/.zshrc

5. 安装常见问题详见Python common build problems

2. windows系统下Pyenv-win工具的安装与配置

1. 已管理员权限打开powershell，临时修改用户策略，安装Pyenv-win。

powershell
## Bypass当前 PowerShell 会话绕过执行策略
## -Scope CurrentUser只对当前会话有效，安全性更高，运行后输入“y”同意
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

## 按装命令
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"

命名运行成功后，cmd中pyenv --version命令查看。

2. pyenv install XX 经常超时问题解决

  修改pyenv-win\libexec\libs目录下（特别提示，对早期pyenv-win是在pyenv-win\libexec目录下）的pyenv-install-lib.vbs文件中的镜像配置mirror="https://www.python.org/ftp/python"修改为 mirror="https://mirrors.huaweicloud.com/python".

3. pyenv-win 基本用法

powershell
   commands     列出所有可用的 pyenv 命令
   local        设置或显示本地应用程序特定的 Python 版本
   latest       打印带有指定前缀的最新安装或已知版本
   global       设置或显示全局 Python 版本
   shell        设置或显示 shell 特定的 Python 版本
   install      安装一个或多个 Python 版本
   uninstall    卸载一个或多个 Python 版本
   update       更新缓存的版本数据库
   rehash       重新生成 pyenv 的 shim 文件（切换 Python 版本后运行此命令）
   vname        显示当前的 Python 版本名称
   version      显示当前的 Python 版本及其来源
   version-name 显示当前的 Python 版本名称
   versions     列出 pyenv 可用的所有 Python 版本
   exec         运行一个可执行文件，首先准备 PATH，将所选 Python 版本的 `bin` 目录放在前面
   which        显示可执行文件的完整路径
   whence       列出包含指定可执行文件的所有 Python 版本

4. 删除 pyenv-win

1. 删除 pyenv-win 文件夹

shell
## 通常在C:\Users\Administrator\目录下
cd C:\Users\Administrator\
## 删除整个 .pyenv 文件夹
Remove-Item -Recurse -Force "$env:USERPROFILE\.pyenv"

2.清理系统环境变量

pyenv-win 会在安装时修改以下环境变量，打开“此电脑” → 右键 → 属性 → 高级系统设置 点击 环境变量，针对以下内容一一删除，删除后重启cmd，pyenv --verison进行验证：