Profile photo
Reese

pyenv 使用：Python 多版本管理和虚拟环境

pyenv 日常使用手册，涵盖安装配置、Python 版本切换，以及配合 venv 管理项目环境。

RunbooksCloud tooling

pyenv 是 Python 版本管理工具。它解决的是：同一台机器上安装多个 Python 解释器，并按全局、项目目录或当前 shell 切换版本。

几个工具的分工大概是：

text
pyenv
  -> 管 Python 解释器版本
  -> 例如 3.9.18 / 3.10.13 / 3.11.9 / 3.12.4

venv / virtualenv
  -> 管项目依赖隔离
  -> 例如这个项目装 Flask 2，另一个项目装 Flask 3

pip / uv / poetry
  -> 管依赖安装、解析和锁定

所以 pyenv 不是 pip 的替代品，也不是虚拟环境本身。最常见组合是：

text
pyenv 选择 Python 版本
venv 创建项目虚拟环境
pip/uv/poetry 安装依赖

什么时候用 pyenv

适合用 pyenv 的场景：

text
本机要同时维护多个 Python 版本
项目 A 要 Python 3.10，项目 B 要 Python 3.12
不想改系统自带 Python
希望进入项目目录后自动切到指定 Python
CI 和本地需要统一 Python 版本

不适合把 pyenv 当成：

text
依赖锁定工具
虚拟环境隔离工具
包管理器
项目构建工具

安装

macOS 推荐 Homebrew：

bash
brew update
brew install pyenv

如果要用 pyenv virtualenv：

bash
brew install pyenv-virtualenv

Linux / WSL 可以用官方安装脚本：

bash
curl https://pyenv.run | bash

Linux 上安装 Python 需要编译依赖。常见依赖包括编译器、zlib、openssl、readline、sqlite、bz2、lzma 等。缺依赖时通常会在 pyenv install 阶段失败。

Shell 初始化

Zsh 示例，把下面内容放进 ~/.zshrc：

bash
export PYENV_ROOT="$HOME/.pyenv"
[[ -d "$PYENV_ROOT/bin" ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

如果安装了 pyenv-virtualenv，再加：

bash
eval "$(pyenv virtualenv-init -)"

让配置生效：

bash
source ~/.zshrc

检查是否安装成功：

bash
pyenv --version
pyenv versions

安装 Python 版本

查看可安装版本：

bash
pyenv install --list

安装指定版本：

bash
pyenv install 3.11.9
pyenv install 3.12.4

查看本机已安装版本：

bash
pyenv versions

查看当前生效版本：

bash
pyenv version
python --version

卸载版本：

bash
pyenv uninstall 3.11.9

如果新安装的命令没有出现在 shim 里：

bash
pyenv rehash

切换 Python 版本

pyenv 有三个常用作用域。

全局默认版本：

bash
pyenv global 3.12.4

项目目录版本，最常用：

bash
cd my_project
pyenv local 3.11.9
python --version

pyenv local 会在当前目录写入：

text
.python-version

当前 shell 临时版本：

bash
pyenv shell 3.10.14
python --version

优先级：

text
pyenv shell / PYENV_VERSION
  > 当前目录或父目录的 .python-version
  > pyenv global
  > system

排查当前版本来自哪里：

bash
pyenv version
pyenv which python
cat .python-version

pyenv shim 是什么

pyenv 不是直接替换系统 Python，而是在 PATH 前面放一层 shims。

大致流程：

text
shell 执行 python
  -> 找到 ~/.pyenv/shims/python
  -> pyenv 根据优先级判断该用哪个版本
  -> 转发到 ~/.pyenv/versions/<version>/bin/python

所以环境异常时，先看：

bash
which python
pyenv which python
python --version
pyenv version

如果 which python 没有指向 pyenv shim，通常是 shell 初始化或 PATH 顺序有问题。

配合 venv 创建项目环境

pyenv 只负责解释器版本。项目依赖建议放进虚拟环境。

常见项目初始化：

bash
cd my_project
pyenv local 3.11.9
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt

确认当前 Python 和 pip：

bash
which python
python --version
python -m pip --version

退出虚拟环境：

bash
deactivate

.venv/ 是本地生成物，应该进 .gitignore：

gitignore
.venv/

使用 pyenv-virtualenv

如果安装了 pyenv-virtualenv，可以让虚拟环境也由 pyenv 管。

创建虚拟环境：

bash
pyenv virtualenv 3.11.9 my-project-3.11

在项目目录绑定这个环境：

bash
cd my_project
pyenv local my-project-3.11
python --version

删除虚拟环境：

bash
pyenv uninstall my-project-3.11

项目内 .venv 和 pyenv-virtualenv 二选一即可。不要在一个项目里混用多套环境约定。

pip 使用建议

推荐：

bash
python -m pip install <package>
python -m pip install -r requirements.txt
python -m pip show <package>
python -m pip list

少用：

bash
pip install <package>

原因是 python -m pip 明确绑定当前 Python。直接敲 pip 时，它可能来自另一个虚拟环境或另一个 pyenv shim。

常用命令速查

版本安装：

bash
pyenv install --list
pyenv install 3.11.9
pyenv uninstall 3.11.9

版本查看：

bash
pyenv versions
pyenv version
python --version
pyenv which python

版本切换：

bash
pyenv global 3.12.4
pyenv local 3.11.9
pyenv shell 3.10.14

虚拟环境：

bash
python -m venv .venv
source .venv/bin/activate
deactivate

pyenv-virtualenv：

bash
pyenv virtualenv 3.11.9 my-env
pyenv local my-env
pyenv uninstall my-env

排查：

bash
which python
which pip
python --version
python -m pip --version
pyenv version
pyenv which python
echo $VIRTUAL_ENV
python -c "import sys; print(sys.executable)"

排障场景

pyenv install 失败：

text
通常是缺编译依赖。看错误里是否有 openssl、zlib、readline、sqlite、bz2、lzma。

python --version 不是期望版本：

bash
pyenv version
pyenv which python
which python
cat .python-version

pip install 后包还是找不到：

bash
which python
python -m pip --version
python -m pip show <package>
python -c "import sys; print(sys.executable)"

虚拟环境没生效：

bash
echo $VIRTUAL_ENV
which python
source .venv/bin/activate

项目初始化顺序

普通项目可以按这个顺序：

bash
pyenv install 3.11.9
cd my_project
pyenv local 3.11.9
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt

仓库里建议保留：

text
.python-version
requirements.txt / pyproject.toml / lock file
.gitignore 里的 .venv/

这样别人 clone 项目后，至少知道该用哪个 Python、怎么创建环境、怎么安装依赖。