什么是 pyenv？

什么是 pyenv？

pyenv 是一个用于管理 多个 Python 版本 的工具。它允许您在一台机器上安装和切换不同版本的 Python，而不会发生版本冲突。这对于需要在不同项目中使用不同 Python 版本的开发者来说，十分便利。

---

为什么需要 pyenv？

• 版本管理便利：在开发过程中，您可能需要使用不同的 Python 版本。例如，一个项目需要 Python 2.7，另一个需要 Python 3.12。使用 pyenv，可以轻松地在这些版本之间切换。

• 隔离性：避免了系统级的 Python 安装被污染，或者因全局升级 Python 版本而导致旧项目无法运行的情况。

• 易于测试：对于库和框架的开发者，可以方便地在多个 Python 版本下测试代码的兼容性。

---

pyenv 的工作原理

pyenv 修改了 PATH 环境变量，从而控制了 Python 命令的解析方式。当您切换 Python 版本时，pyenv 会将对应版本的可执行文件路径放在 PATH 的前面。

---

安装 pyenv

1. 安装依赖项

在安装 pyenv 之前，需要安装一些构建 Python 所需的依赖库。

• 对于 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 \
  libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev \
  python-openssl git
  

• 对于 CentOS/Fedora 系统：

  sudo yum install -y gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel \
  openssl-devel xz xz-devel libffi-devel findutils
  

2. 安装 pyenv

有多种方法安装 pyenv，最简单的是通过 curl 脚本安装：

curl https://pyenv.run | bash

或者使用 git 克隆：

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

3. 配置环境变量

将以下内容添加到您的 shell 配置文件中，例如 ~/.bashrc、~/.bash_profile、~/.zshrc 等：

# pyenv
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

然后，重新加载 shell 配置文件：

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

4. 验证安装

输入 pyenv --version，如果成功安装，应该会显示版本号，例如：

pyenv 2.3.17

---

使用 pyenv 的实际例子

1. 列出可用的 Python 版本

您可以使用以下命令查看所有可安装的 Python 版本：

pyenv install --list

输出示例（部分）：

3.10.12
3.11.4
3.12.0

2. 安装指定版本的 Python

安装 Python 3.12.0：

pyenv install 3.12.0

注意：

• 有时最新版本的 Python 可能还没有打包到 pyenv 中，请确保您运行 pyenv update（如果您使用了插件）或者 git pull 更新 pyenv。

安装多个版本：

pyenv install 3.10.12
pyenv install 3.11.4

3. 设置全局 Python 版本

将全局 Python 版本设置为 3.12.0：

pyenv global 3.12.0

验证当前的全局 Python 版本：

python --version

输出：

Python 3.12.0

4. 设置本地（项目级别）Python 版本

在项目目录下，设置本地 Python 版本为 3.10.12：

cd /path/to/your/project
pyenv local 3.10.12

这将在项目目录下创建一个 .python-version 文件，指定了该目录使用的 Python 版本。

验证本地 Python 版本：

python --version

输出：

Python 3.10.12

即使全局版本是 3.12.0，但在该项目目录下，Python 版本被重写为 3.10.12。

5. 临时切换（shell 级别）Python 版本

如果您想在当前 shell 会话中临时使用某个 Python 版本：

pyenv shell 3.11.4

验证：

python --version

输出：

Python 3.11.4

关闭终端或退出会话后，Python 版本会恢复到之前的设置。

6. 列出已安装的 Python 版本

pyenv versions

输出示例：

  system
* 3.10.12 (set by /home/user/.pyenv/version)3.11.43.12.0

• 带 * 的是当前生效的版本。

7. 卸载 Python 版本

如果不再需要某个 Python 版本，可以卸载：

pyenv uninstall 3.10.12

---

与虚拟环境结合使用

虽然 pyenv 本身主要管理 Python 版本，但在实际开发中，我们通常还需要为每个项目创建虚拟环境。这里我们可以使用 pyenv-virtualenv 插件。

1. 安装 pyenv-virtualenv

通过 git 克隆安装：

git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

在 shell 配置文件中添加初始化：

eval "$(pyenv virtualenv-init -)"

重新加载 shell 配置文件：

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

2. 创建虚拟环境

基于某个 Python 版本创建虚拟环境：

pyenv virtualenv 3.12.0 myenv312

这将在 Python 3.12.0 的基础上创建一个名为 myenv312 的虚拟环境。

3. 激活虚拟环境

设置本地使用该虚拟环境：

pyenv local myenv312

验证：

python --version

输出：

Python 3.12.0

查看当前的 pyenv 版本设置：

pyenv version

输出：

myenv312 (set by /path/to/your/project/.python-version)

4. 管理虚拟环境中的依赖

现在，您可以像使用普通的虚拟环境一样，安装依赖包：

pip install requests numpy

这些包将安装在 myenv312 虚拟环境中，不会影响全局的 Python 版本。

5. 切换虚拟环境

如果您有多个虚拟环境，可以使用 pyenv activate 和 pyenv deactivate 进行切换：

pyenv activate myenv312
# ... 进行开发 ...
pyenv deactivate

---

实际应用示例

场景：同时开发两个项目，分别需要 Python 3.10 和 Python 3.12

1. 安装所需的 Python 版本

pyenv install 3.10.12
pyenv install 3.12.0

2. 为每个项目创建虚拟环境

pyenv virtualenv 3.10.12 project310_env
pyenv virtualenv 3.12.0 project312_env

3. 为项目设置本地 Python 虚拟环境

• 项目 1（Python 3.10）：

  cd /path/to/project1
  pyenv local project310_env
  

• 项目 2（Python 3.12）：

  cd /path/to/project2
  pyenv local project312_env
  

4. 在各自的环境中安装依赖

• 项目 1：

  cd /path/to/project1
  pip install -r requirements.txt
  

• 项目 2：

  cd /path/to/project2
  pip install -r requirements.txt
  

这样，每个项目都有自己的 Python 版本和依赖环境，互不干扰。

---

pyenv 常用命令速览

• 查看可安装的 Python 版本

  pyenv install --list
  

• 安装指定版本的 Python

  pyenv install <version>
  

• 卸载指定版本的 Python

  pyenv uninstall <version>
  

• 列出已安装的 Python 版本

  pyenv versions
  

• 设置全局 Python 版本

  pyenv global <version>
  

• 设置本地（目录级别）Python 版本

  pyenv local <version>
  

• 在当前 shell 会话中设置 Python 版本

  pyenv shell <version>
  

• 查看当前使用的 Python 版本

  pyenv version
  

• 升级 pyenv

  cd $(pyenv root)
  git pull
  

---

注意事项

• 依赖问题：在安装 Python 版本时，可能会遇到依赖缺失问题。请根据错误提示安装缺少的库。

• 权限问题：确保您的用户对 pyenv 的安装目录有读写权限。

• 路径问题：如果命令不起作用，检查是否正确配置了环境变量 PYENV_ROOT 和 PATH。

• 冲突问题：如果系统中存在其他版本管理器（如 Anaconda），可能会导致冲突。确保 pyenv 的路径位于 PATH 的前面。

---

总结

• pyenv 提供了强大的 Python 版本管理功能，使得在同一台机器上管理多个 Python 版本变得简单。

• 结合 pyenv-virtualenv，可以为每个项目创建独立的虚拟环境，进一步隔离项目依赖。

• 通过 pyenv 的全局、本地和 shell 设置，可以灵活地控制 Python 版本的生效范围。

• 正确安装和配置 pyenv，可以极大地提高开发效率，避免因 Python 版本冲突导致的问题。

---

参考资料

• pyenv GitHub 仓库
• pyenv-virtualenv GitHub 仓库
• pyenv 常见问题解答

---