pyenv 安装与使用指南

nvm 安装和使用教程 解决的是 Node.js 版本切换，pyenv 解决的是 Python 版本切换。公司项目、个人脚本、老服务混在一台机器上时，这个问题很常见。

安装

Linux 上可以用官方安装脚本：

1
curl https://pyenv.run | bash

然后把初始化脚本加到 shell 配置里：

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

重开终端后确认：

1
pyenv --version

常用命令

1
pyenv install 3.12.8
2
pyenv versions
3
pyenv local 3.12.8
4
python --version
5
pyenv uninstall 3.11.9

pyenv local 会写入 .python-version，建议提交到项目仓库。这样别人进入目录后就知道项目应该用哪个 Python。

和 uv 怎么配合

pyenv 管 Python 解释器版本，uv 安装和使用教程 管虚拟环境、依赖和锁文件。两者可以一起用：

1
pyenv local 3.12.8
2
uv venv
3
uv sync

如果你只做新项目，uv 自带的 uv python install 也能解决一部分 Python 版本问题；如果你要维护老项目，pyenv 仍然很顺手。

常见问题

编译 Python 失败时，通常是系统缺少依赖。Debian / Ubuntu 先装这些：

1
sudo apt update
2
sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev

如果 python --version 没变化，先检查 shell 是否加载了 pyenv init。

总结

pyenv 最适合“多项目、多 Python 版本”的开发机。项目里用 .python-version 固定版本，再用 uv 或 pip 管依赖，环境问题会少很多。更多细节看 pyenv 官方仓库。