pyenv新手必看：快速了解与上手使用 – wiki基地

作者： /

pyenv新手必看：快速了解与上手使用，告别Python版本管理混乱！

Python，作为当今最受欢迎的编程语言之一，被广泛应用于Web开发、数据科学、人工智能、自动化脚本等众多领域。然而，随着你参与的项目越来越多，或者在不同项目之间切换时，一个常见的问题很快就会浮现：Python版本管理。

也许你的旧项目依赖于Python 3.7，而新项目要求Python 3.9甚至最新的Python 3.11。系统自带的Python版本可能又是另一个版本。不同的版本之间，标准库、语法特性可能存在差异，更重要的是，各种第三方库的兼容性问题会让你头疼不已。此外，如果你直接在系统Python环境中全局安装库，很容易导致依赖冲突，甚至破坏系统本身的Python环境（特别是在macOS或Linux上，系统可能依赖特定版本的Python）。

手动管理多个Python版本非常繁琐且容易出错。有没有一个工具，能够帮助我们轻松地在多个Python版本之间切换，并且为每个项目隔离其所需的Python环境呢？

答案就是 pyenv。

什么是 pyenv？

pyenv 是一个简单而强大的Python版本管理工具。它允许你在同一台计算机上安装和管理多个Python版本，并轻松地在它们之间进行切换。最重要的是，它不会干扰系统原有的Python环境。

pyenv 的核心思想是修改你的 PATH 环境变量，并将一个叫做 “shims” 的目录放在 PATH 的最前面。当你运行 python、pip 或其他Python相关命令时，操作系统会首先在这个 shims 目录中查找。shims 目录中的每个文件都是一个简单的脚本，它会根据你当前所处的目录、设置的环境变量等信息，判断出你应该使用哪个Python版本，然后将命令重定向到正确的Python可执行文件上。

简单来说，pyenv 帮你解决了以下痛点：

  1. 多版本共存： 轻松安装和管理任意数量的Python版本（包括各种发行版，如CPython、Jython、PyPy、Anaconda等）。
  2. 无缝切换： 根据你的需求，在全局、单个项目目录、甚至当前终端会话中快速切换Python版本。
  3. 隔离性： 避免不同项目之间的Python版本和库依赖冲突。
  4. 保护系统Python： 不会触碰或破坏操作系统自带的Python环境。

理解 pyenv 的工作原理（特别是 shims）对于排除故障非常有帮助。记住，pyenv 本身不负责创建和管理虚拟环境（Python自带的 venv 或第三方工具 virtualenv 负责这个）。但 pyenv 有一个非常重要的插件 pyenv-virtualenv，它能让你方便地将虚拟环境与 pyenv 管理的特定Python版本关联起来，实现版本和依赖的双重隔离。

为什么要使用 pyenv？实际场景举例

让我们通过几个具体的场景来理解 pyenv 的价值：

  • 场景一：维护旧项目与开发新项目

    • 你有一个用了几年的项目，它在 Python 3.7 上运行良好，并且依赖一些在 Python 3.7 下测试通过的库。
    • 现在你开始一个新的项目，想使用 Python 3.10 的新特性和性能优化。
    • 没有 pyenv，你可能需要在系统上安装多个 Python 版本，并手动调整 PATH，这非常容易出错，而且很难确保不同项目使用了正确的版本。
    • 使用 pyenv，你可以 pyenv install 3.7.12 和 pyenv install 3.10.5。在旧项目目录里运行 pyenv local 3.7.12，在新项目目录里运行 pyenv local 3.10.5。进入任一项目目录，python 命令就会自动指向对应的版本，互不干扰。

  • 场景二：测试代码在不同 Python 版本下的兼容性

    • 你写了一个Python库，希望确保它能在 Python 3.8、3.9、3.10 这几个主流版本下都能正常工作。
    • 没有 pyenv，你需要手动安装这些版本，并可能需要修改系统 PATH 或使用 Docker/虚拟机，过程繁琐。
    • 使用 pyenv，安装这几个版本后，你可以轻松地在不同的终端会话中使用 pyenv shell <version> 命令切换到特定的版本进行测试，或者在自动化测试脚本中通过设置环境变量来实现多版本测试。

  • 场景三：避免全局安装库带来的依赖冲突

    • 如果你直接使用系统 Python 并通过 pip install ... 安装库，所有库都会安装到系统 Python 的 site-packages 目录。不同项目所需的库版本冲突（例如，项目A需要库X的v1，项目B需要库X的v2）就会发生，导致某个项目无法正常运行。
    • pyenv 结合虚拟环境（pyenv-virtualenv 插件）完美解决了这个问题。你可以创建一个基于 Python 3.9 的虚拟环境用于项目A，再创建一个基于 Python 3.10 的虚拟环境用于项目B。每个虚拟环境都有自己独立的 site-packages 目录，各自安装所需的库，彻底隔离。

看完这些场景，相信你已经对 pyenv 的作用有了初步认识。接下来，我们将进入实践环节。

pyenv 的安装

pyenv 的安装相对简单，推荐使用其官方提供的自动安装脚本。在此之前，你需要确保系统安装了 Git。

1. 前置条件

在安装 pyenv 以及 使用 pyenv 安装各种 Python 版本之前，你的系统需要准备一些构建工具和依赖库。这是因为 pyenv 通常是从源代码编译安装 Python 的。如果缺少这些依赖，pyenv install 命令会失败。

不同操作系统的依赖有所不同：

  • macOS (使用 Homebrew):
    bash
    brew update
    brew install openssl readline sqlite3 xz zlib tcl-tk
    Homebrew 会安装大部分必需的构建工具（如 GCC/Clang、Make 等）。

  • Debian/Ubuntu:
    bash
    sudo apt-get update
    sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
    libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils \
    tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

  • Fedora/CentOS/RHEL:
    bash
    sudo yum update
    sudo yum install -y gcc zlib-devel bzip2-devel readline-devel sqlite-devel \
    wget curl llvm ncurses-devel xz-devel tk-devel libffi-devel openssl-devel
    或对于较新的 Fedora 使用 dnf:
    bash
    sudo dnf update
    sudo dnf install -y @development zlib-devel bzip2-devel readline-devel \
    sqlite-devel wget curl llvm ncurses-devel xz-devel tk-devel libffi-devel \
    openssl-devel

  • Alpine Linux:
    bash
    sudo apk update
    sudo apk add --no-cache build-base openssl-dev bzip2-dev readline-dev \
    sqlite-dev wget curl ncurses-dev xz-dev zlib-dev tk-dev \
    libffi-dev

务必安装这些依赖，否则在后续执行 pyenv install <python_version> 时很可能会遇到编译错误。

2. 使用 pyenv-installer 脚本安装 (推荐)

这是最简单便捷的方法。打开你的终端，运行以下命令：

bash
curl https://pyenv.run | bash

这个脚本会：
1. 克隆 pyenv 及其常用的插件（如 pyenv-update, pyenv-virtualenv, pyenv-which-ext, pyenv-doctor）到 ~/.pyenv 目录。
2. 自动在你的 shell 配置文件（如 ~/.bashrc, ~/.zshrc, ~/.profile）中添加必要的配置行，以便 pyenv 能够正常工作。

安装脚本会提示你需要在 shell 配置文件中添加的行。这些行通常看起来像这样：

“`bash

添加到你的 ~/.bashrc 或 ~/.zshrc 文件末尾

export PYENV_ROOT=”$HOME/.pyenv”
export PATH=”$PYENV_ROOT/bin:$PATH”
eval “$(pyenv init –path)”
eval “$(pyenv init -)”
eval “$(pyenv virtualenv-init -)” # 如果安装了 pyenv-virtualenv 插件
“`

重要步骤：配置你的 Shell 环境

即使安装脚本尝试自动添加，你最好还是手动确认或编辑你的 shell 配置文件（根据你使用的 shell，可能是 ~/.bashrc, ~/.zshrc, ~/.profile 等）。使用文本编辑器打开文件，将上面所示的几行添加到文件末尾。

添加完成后，你需要 重新加载你的 shell 配置 或者 关闭并重新打开终端窗口，使更改生效。

重新加载配置的命令通常是：

bash
source ~/.bashrc # 如果使用 bash
source ~/.zshrc # 如果使用 zsh

3. 验证安装

配置并重新加载 shell 后，运行以下命令验证 pyenv 是否安装成功：

bash
pyenv --version

如果命令输出了 pyenv 的版本号，说明安装成功。例如：

pyenv 2.3.13

你还可以运行 pyenv doctor 来检查你的系统是否满足安装 Python 版本的条件：

bash
pyenv doctor

它会检查一些关键的依赖库，并告诉你可能缺少哪些。根据 doctor 的输出，你可以回到步骤1安装缺失的依赖。

pyenv 的核心使用

现在 pyenv 已经安装好了，我们来学习如何使用它的核心功能。

1. 查看可用的 Python 版本

pyenv 可以安装各种不同的 Python 版本。要查看所有可用的版本列表，运行：

bash
pyenv install --list

这个命令会输出一个很长的列表，包含各种 CPython、Miniconda、Anaconda、Jython、PyPy 等版本。你可以从中选择你需要的版本号进行安装。

示例输出片段：

...
3.9.10
3.9.11
3.9.12
3.10.0
3.10-dev
3.10.1
3.10.2
3.10.3
3.10.4
3.10.5
3.11.0
3.11-dev
3.11.1
3.11.2
...
miniconda3-4.7.12
miniconda3-4.8.0
...
anaconda3-2022.05
...

2. 安装一个 Python 版本

选择你想要安装的版本号（例如，3.9.12），然后运行 pyenv install 命令：

bash
pyenv install 3.9.12

注意：

  • 这个过程需要从互联网下载 Python 源代码并进行编译。根据你的网络速度和电脑性能，这可能需要几分钟到半小时甚至更长时间。请耐心等待。
  • 如果在编译过程中出现错误，很可能是缺少了前面提到的系统依赖库。请仔细检查 pyenv doctor 的输出，并安装所有推荐的依赖。
  • 你可以并行安装多个版本。

安装完成后，pyenv 会把这个版本的 Python 安装在 ~/.pyenv/versions/3.9.12 目录下。

3. 查看已安装的 Python 版本

要查看你已经通过 pyenv 安装了哪些 Python 版本，运行：

bash
pyenv versions

示例输出：

system
3.8.12
* 3.9.12 (set by /home/youruser/.pyenv/version)
3.10.5

输出解释：

  • system：表示系统自带的 Python 版本。
  • 列表中的数字：表示你通过 pyenv install 安装的 Python 版本。
  • 行首的 * 号：表示当前正在使用的 Python 版本。
  • 括号中的信息：说明当前版本是如何被设置的（例如，通过全局 .pyenv/version 文件）。

4. 切换 Python 版本：全局、局部和 Shell

pyenv 提供了三种方式来切换 Python 版本，它们有不同的作用范围和优先级：

  • 全局 (global): 设置默认的 Python 版本。这个设置会写入 ~/.pyenv/version 文件。当你不在任何设置了局部版本或 Shell 版本的地方时，就会使用全局版本。

    bash
    pyenv global 3.9.12

    设置后，重新打开一个终端窗口，或者在当前终端中运行 python --version，应该会显示 3.9.12。你也可以通过 pyenv versions 查看 * 是否已经移到 3.9.12。

    要取消全局设置，恢复使用系统版本：

    bash
    pyenv global system

  • 局部 (local): 设置当前目录及其子目录使用的 Python 版本。这个设置会创建一个 .python-version 文件在当前目录下。当你进入这个目录时，pyenv 会自动切换到指定的版本。这是管理项目特定 Python 版本的推荐方式。

    进入你的项目目录：

    bash
    cd path/to/your/project

    设置该目录的 Python 版本：

    bash
    pyenv local 3.10.5

    现在，在这个项目目录中运行 python --version 应该会显示 3.10.5。离开这个目录，切换到其他目录，再运行 python --version，应该会恢复到全局版本或其他更高优先级的版本。

    要取消局部设置，删除当前目录下的 .python-version 文件即可：

    “`bash
    rm .python-version

    或者

    pyenv local –unset
    “`

  • Shell: 设置当前终端会话使用的 Python 版本。这个设置只在当前的终端窗口有效，关闭终端或打开新的终端窗口后就会失效。它的优先级最高，常用于临时切换版本进行测试。

    在当前终端中：

    bash
    pyenv shell 3.8.12

    现在，在这个终端中运行 python --version 会显示 3.8.12。打开一个新的终端窗口，python --version 则会使用全局或其他版本。

    要取消 Shell 设置：

    bash
    pyenv shell --unset

版本切换的优先级：

pyenv 决定使用哪个 Python 版本的顺序是：

  1. Shell 版本 (通过 pyenv shell 设置，优先级最高)
  2. 局部版本 (通过 pyenv local 设置，写入 .python-version 文件)
  3. 全局版本 (通过 pyenv global 设置，写入 ~/.pyenv/version 文件)
  4. 系统版本 (如果 pyenv global system 被设置，或者没有其他版本被设置时)

理解这个优先级对于理解 pyenv 的行为非常重要。

5. 卸载 Python 版本

如果你不再需要某个 Python 版本，可以通过 pyenv uninstall 命令将其移除：

bash
pyenv uninstall 3.8.12

pyenv 会询问你是否确认卸载，输入 y 并回车即可。

6. pyenv rehash (了解即可)

在旧版本的 pyenv 中，当你安装新的 Python 版本或者使用 pip install 安装了包含可执行文件的库（例如安装了 virtualenv 或 tox）之后，需要运行 pyenv rehash 命令来更新 ~/.pyenv/shims 目录下的垫片脚本，否则新安装的可执行文件可能无法找到。

然而，新版本的 pyenv 大多数情况下会自动完成这个操作，你很少需要手动运行 pyenv rehash。但如果你发现安装了某个工具后无法直接通过命令行名称执行（例如安装了 tox 后输入 tox 命令找不到），可以尝试运行 pyenv rehash。

使用 pyenv-virtualenv 管理虚拟环境

前面提到，pyenv 负责管理 Python 解释器 的版本，而虚拟环境（Virtual Environment）负责隔离 项目所需的第三方库。这两者是互补的，结合使用可以达到最好的效果。

pyenv-virtualenv 是 pyenv 的一个插件，它让使用虚拟环境变得更加方便，特别是将虚拟环境与 pyenv 管理的特定 Python 版本关联起来。

如果你使用了 pyenv-installer 脚本安装 pyenv，那么 pyenv-virtualenv 插件通常已经默认安装了。你可以通过 pyenv virtualenvs 命令来检查它是否可用。

1. 创建虚拟环境

使用 pyenv virtualenv 命令基于一个特定的 Python 版本创建一个虚拟环境。命令格式为 pyenv virtualenv <python_version> <environment_name>。<python_version> 必须是你已经通过 pyenv install 安装过的版本。

例如，基于 Python 3.10.5 创建一个名为 my-project-env 的虚拟环境：

bash
pyenv virtualenv 3.10.5 my-project-env

这个命令会在 ~/.pyenv/versions 目录下创建一个名为 my-project-env 的虚拟环境，它实际上是基于 ~/.pyenv/versions/3.10.5 创建的。

创建成功后，你可以通过 pyenv virtualenvs 命令查看已创建的虚拟环境：

bash
pyenv virtualenvs

示例输出：

3.8.12
3.9.12
3.10.5
my-project-env (created from /home/youruser/.pyenv/versions/3.10.5)
system

2. 激活和停用虚拟环境

  • 激活： 使用 pyenv activate <environment_name> 命令激活虚拟环境。这会修改你的 shell 提示符，显示当前所在的虚拟环境名称。

    bash
    pyenv activate my-project-env

    激活后，你的命令行提示符前面可能会显示 (my-project-env)。此时，python 和 pip 命令都会指向 my-project-env 这个虚拟环境中的解释器和包管理器。

    你可以在这个环境中自由地安装库，它们只会安装到这个环境隔离的目录中，不会影响其他环境或系统。

    bash
    pip install requests numpy

  • 停用： 使用 pyenv deactivate 命令停用虚拟环境。

    bash
    pyenv deactivate

    这会让你回到激活前的状态，通常是全局 Python 版本或者通过 pyenv local 设置的局部版本。

3. 将虚拟环境关联到项目目录 (最常用工作流)

手动激活和停用虚拟环境有点麻烦。结合 pyenv local 是最便捷的项目工作流。

进入你的项目目录：

bash
cd path/to/your/another-project

使用 pyenv local 命令将之前创建的虚拟环境与当前目录关联起来。注意，这里指定的版本名称就是虚拟环境的名称：

bash
pyenv local my-project-env

这会在当前目录创建一个 .python-version 文件，内容就是 my-project-env。

现在，每当你进入 path/to/your/another-project 目录时，pyenv 会检测到 .python-version 文件，并自动激活 my-project-env 虚拟环境。离开这个目录时，环境会自动停用。

这是使用 pyenv 和 pyenv-virtualenv 管理项目的推荐方式：

  1. 使用 pyenv install 安装项目所需的 Python 版本（例如 3.9.12）。
  2. 进入项目目录。
  3. 使用 pyenv virtualenv 3.9.12 my-project-name-env 创建一个基于该版本、名称与项目相关的虚拟环境。
  4. 使用 pyenv local my-project-name-env 将虚拟环境与当前项目目录关联。
  5. 现在，在该目录下，python 和 pip 都指向并作用于这个独立的虚拟环境。使用 pip install -r requirements.txt 安装项目依赖即可。

4. 卸载虚拟环境

使用 pyenv uninstall <environment_name> 命令卸载虚拟环境：

bash
pyenv uninstall my-project-env

常见问题与故障排除

  • pyenv install 编译失败： 90% 的原因是因为缺少前面提到的系统依赖库。仔细阅读错误信息，对照你的操作系统，安装缺失的依赖后再试。可以使用 pyenv doctor 检查。
  • 安装后 python --version 仍然显示系统版本：
    • 确保你在 shell 配置文件中添加了 pyenv init 等相关的配置行。
    • 确保你在添加配置后重新加载了 shell (source ~/.bashrc) 或重新打开了终端。
    • 检查你的 PATH 环境变量，~/.pyenv/shims 目录应该出现在 PATH 的最前面。
    • 运行 pyenv versions，确认你设置的全局/局部版本前面有 * 号。
    • 确认你当前不在一个设置了更高优先级（Shell > Local > Global）版本的目录或 Shell 会话中。
  • pyenv virtualenv 命令不存在： 确保 pyenv-virtualenv 插件已正确安装在 ~/.pyenv/plugins 目录下，并且你的 shell 配置中包含 eval "$(pyenv virtualenv-init -)" 并已重新加载。
  • 激活虚拟环境后提示符没有变化： 确保你的 shell 配置中包含 eval "$(pyenv virtualenv-init -)" 并已重新加载。这个命令负责设置 shell 提示符的修改。
  • Homebrew 安装的 Python vs pyenv 安装的 Python： 如果你在 macOS 上使用 Homebrew 安装了 Python，它也会修改你的 PATH。建议使用 pyenv 来管理 Python 版本，并通过 Homebrew 安装 pyenv 及其依赖，但避免使用 Homebrew 直接 安装 Python 解释器，以避免冲突。让 pyenv 来全权管理 Python 版本。

总结

pyenv 是 Python 开发者管理多个 Python 版本不可或缺的工具。它通过巧妙的 shim 机制，实现了不同版本之间的无缝切换，并保护了你的系统环境。结合 pyenv-virtualenv 插件，你可以为每个项目配置独立的 Python 版本和库环境，彻底告别版本冲突和依赖地狱。

从理解 pyenv 的作用和必要性，到完成安装和配置，再到掌握 install, versions, global, local, shell 等核心命令，以及利用 pyenv-virtualenv 进行虚拟环境管理，你现在已经具备了使用 pyenv 的基础。

关键 takeaways:

  • pyenv 管理 Python 解释器版本。
  • 虚拟环境（通常通过 pyenv-virtualenv 插件配合使用）管理项目依赖库。
  • pyenv local <env_name> 是项目中最常用的版本管理方式。
  • 确保安装 pyenv 前安装必要的系统依赖库，以及安装后正确配置 shell 环境。

花一些时间练习使用 pyenv 的各种命令，将它融入到你的日常开发流程中，你将体验到前所未有的顺畅和高效。告别 Python 版本管理的混乱，专注于你的代码吧！

进一步学习

  • pyenv 官方文档： https://github.com/pyenv/pyenv
  • pyenv-virtualenv 官方文档： https://github.com/pyenv/pyenv-virtualenv

祝你在 Python 的世界里开发愉快！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部