pyenv 手把手入门：告别 Python 版本混乱，多版本一键切换

pyenv 手把手入门：告别 Python 版本混乱，多版本一键切换

【免费下载链接】pyenvSimple Python version management项目地址: https://gitcode.com/GitHub_Trending/py/pyenv

pyenv 是一款用纯 shell 脚本编写的轻量级 Python 版本管理器（version manager，帮你在一台机器上同时装、管、切多个 Python）。它不打扰系统自带环境，不需要"用 Python 来安装 Python"，也不需要把什么东西塞进你的 shell 里常驻——靠一个叫 shims 的垫片目录（加进 PATH 的一堆小脚本）来决定每次运行的是哪个版本。老项目 3.9、新项目 3.12、临时测试 2.7？pyenv 让它们和平共处，一条命令切换。

🧩 先说痛点：一台机器，多个 Python，怎么都不带乱

你是不是也遇到过这种局面：手上一个老项目只认 Python 3.9，新开的仓库又要求 3.12，而系统里那个 Python 3.6 还不敢动——系统工具依赖它，升级一步错全盘错。

常见的解法各有一堆麻烦：Docker 太重、手动改 PATH 容易搞乱、每次装新版本都像拆弹。pyenv 的思路很"UNIX 味道"：只做一件事，并且做好。它把每个版本装在独立的目录里，你真正需要做的只是"告诉它现在用哪个"，切换的颗粒度可以细到全局、单个项目目录、甚至当前这个终端窗口。

⚡ 快速上手：三步装好并跑起第一个版本

整个过程不到三分钟。

第一步，把 pyenv 克隆到~/.pyenv（推荐放在家目录）：

git clone https://gitcode.com/GitHub_Trending/py/pyenv ~/.pyenv

（如果不想手动 clone，官方也提供curl -fsSL https://pyenv.run | bash的一键脚本，效果相同。）

第二步，让 shell 认识它，把下面三行追加到~/.bashrc（zsh 用户改放~/.zshrc），然后exec "$SHELL"重启终端生效：

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

第三步，安装第一个 Python 版本并设为全局默认：

pyenv install 3.12.4 pyenv global 3.12.4

装完跑一下python --version，看到 3.12.4 就成功了。下面是实际安装本地 Python 过程的动态演示：

小提醒：编译安装 Python 需要系统装好构建依赖（Linux 下一般是libssl-dev、zlib1g-dev、libffi-dev等），装失败大多是因为缺它们，而不是 pyenv 的问题。

🧭 三个开关加一个机制：五分钟看懂版本到底怎么切

pyenv 的版本选择只有三个"开关"，分别对应三个使用范围：

典型用法：pyenv global定一个稳妥的默认值；cd进某个项目后执行pyenv local，此后在这个目录里干活就是项目专属版本，而.python-version文件本身建议提交到代码仓库，队友 clone 下来自动就是对的版本。

那它是怎么做到"目录一变，Python 就变"的？原理一句话：shims 机制。pyenv 在自己目录里放了一组垫片脚本并把它加进PATH，你敲python时实际先执行垫片，垫片再根据下面的优先级去查"该用哪个版本"：

1. PYENV_VERSION环境变量（pyenv shell设置的）
2. 当前目录的.python-version文件
3. 逐级向上查找父目录的.python-version
4. 全局$PYENV_ROOT/version文件

也就是说优先级从上到下递减，越"靠近你"的设置越优先。下面这张图展示了多版本列表、全局切换和按目录取版本的完整效果：

🚀 进阶工作流：把版本管理用到顺手

装好了基础，这几个命令能让效率再上一个台阶。

先查后装。不要盲装版本号，先看仓库支持哪些：

pyenv install --list

多版本共存。测试跨版本兼容性时（配合 tox 这类工具尤其有用），可以一次声明多个版本，排在前面的优先：

pyenv local 3.12.4 3.9.7

新装了包就 rehash。pip install了带命令行工具的新包之后，执行一次pyenv rehash刷新垫片，否则可能找不到新命令。

用完的及时清理：pyenv uninstall 3.8.10直接移除旧版本，不占空间。随时用pyenv version（显示当前版本及来源）和pyenv versions（列出全部已装版本）确认状态。

⚠️ 三个容易踩的坑，提前说清楚

• pip 装完新包命令找不到：不是安装失败，是垫片没刷新，跑一次pyenv rehash就好。
• .python-version别忘提交：它只在本地生效，不提交到仓库的话，队友的"项目版本"就失效了。
• pyenv 不管虚拟环境：它只管"用哪个 Python"，不管"装哪些包"。想要包级别的隔离，还是老老实实配python -m venv或 pyenv-virtualenv 插件，两者是互补关系，不是替代关系。

所有命令的完整说明都在仓库的 COMMANDS.md，安装细节与原理（PATH、shims、版本选择）可翻 README.md 的 "How It Works" 一节；仓库里的 plugins/ 目录也内置了像 pyenv-binary 这样的官方插件，想让安装走二进制预编译包的可以去看看。

写到这里，你手上已经有了一个干净的默认版本、一套按项目自动切换的规则，以及随时能加进 PATH 的备用版本。下次再有"这个老项目怎么跑"的困扰时，答案就一行：pyenv local 3.9.7，然后回去专心写代码吧。

【免费下载链接】pyenvSimple Python version management项目地址: https://gitcode.com/GitHub_Trending/py/pyenv