Windows 上管 Python 版本：pyenv-win 和官方的 Python Install Manager

Windows 上同时跑几个 Python 版本，一直是个不太体面的事。上个月给一台新机器配环境，把两套方案都装了一遍：社区里用了很多年的 pyenv-win，和官方从 3.14 开始推的 Python Install Manager。折腾完记点东西，省得下次再踩一遍。

结论放在前面：新机器、只跑 Windows、不想折腾，就用官方的 Python Install Manager。pyenv-win 没到不能用的地步，只是在现在的 Windows 上，它要解决的问题和它带来的麻烦已经不太成比例。下面是两边实际装下来、用下来的差别，你自己判断。

先把名字对上

这两样东西经常被当成同一类，先分清楚。

pyenv-win 不是 pyenv 的 Windows 版。它是另一批人从 rbenv-win 分出来、再按 pyenv 的命令习惯改的移植版，命令名字一样（pyenv install、pyenv global），实现完全是另一套：本体是一堆 PowerShell 和批处理脚本。你在 Linux 上攒的 pyenv 经验，有一部分能带过来，有一部分带不过来。pyenv 官方是不支持 Windows 的，这一点它 README 里写得很直接。

Python Install Manager 是 PSF 官方出的，内部代号 PyManager，安装后的界面名就叫 Python Install Manager，能用的命令是 py、pymanager、python、python3。PEP 773 给它的一句话定位是 replacement installer tool——这个 replacement 替换的是传统那个 python-3.x.x-amd64.exe 安装包，不是 conda，也不是 venv 和 uv。

所以它们只在「在一台机器上装多个解释器并随时切」这一层算同类。再往下走一层，两边的边界就不一样了，后面会说到。

装一遍的区别

pyenv-win 官方 README 给的是 PowerShell 脚本 install-pyenv-win.ps1，一行拉下来执行。国内网络下这一步通常是第一个坎，raw.githubusercontent.com 经常连不上，得先找镜像把脚本存到本地再跑。

装完之后有两件事必须做对。一是 %USERPROFILE%\.pyenv\pyenv-win\bin 和 ...\pyenv-win\shims 这两个目录要排在 PATH 最前面，加完要重开终端（FAQ 里还提到个别情况下得注销重登，只开新窗口不生效）。二是 Win10 1905 之后系统自带「应用执行别名」，微软在 WindowsApps 目录里放了两个叫作 python.exe / python3.exe 的占位程序，PATH 顺序没排对的时候，敲 python 会直接弹出应用商店。得去「设置 → 应用 → 高级应用设置 → 应用执行别名」里把 Python 的那两个开关关掉。这两条我第一次装的时候全踩了。

日常还有一条容易忘的：每装一个新版本，或者用 pip 装了带命令行的包，都要执行一次 pyenv rehash 重新生成 shim，而且这个命令不能在 .pyenv 目录里面执行。忘了的典型症状是新装的命令行工具找不到、或者版本还是旧的。

官方这套就简单得多，一行：

winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

也可以去 python.org 的下载页拿 .msix 双击装，命令行里对应的是 Add-AppxPackage。装完开个新终端，py --version 就有反应。不用改 PATH，不用 rehash，也不用重开两次终端——它走的是 Windows 的应用执行别名机制，解释器装在哪、有哪些版本，由它自己记账。

这里也有个坑：如果机器上以前装过单独分发的 py.exe（就是那个老的 Python launcher），它会抢在后装的这个之前生效。症状是 py -V:3.13 这种参数不被识别，或者报 can't open file。要么去「应用和功能」里把 Python launcher 卸掉，要么改用它提供的 pymanager 命令绕开这个名字冲突。官方文档把这个现象写在排错一节里了。

日常命令对照

官方的 -V: 参数必须放在其他参数前面，py -V:3.12 对，py xxx.py -V:3.12 不对。另外它在比较版本号时是按数字段比的，-V:3.1 不会匹配到 3.10，这点比字符串前缀匹配靠谱。

差距在哪儿

真正拉开距离的不是命令多少，是这两样东西各自管到哪儿。

官方这套只管解释器，不管依赖，也不管虚拟环境。 激活了 venv 它就跟着用 venv 的解释器，但它自己不创建、不管理虚拟环境，也不装依赖——PEP 里连「顺手把依赖也管了」这条提案都明确否掉了。有点反直觉的是它连全局的 pip 命令都不提供，要用就 python -m pip，或者在 venv 里激活之后用。所以它取代不了 pip/venv/uv/poetry 中的任何一个，只是把「系统里有哪些 Python」这一层收干净了。

它只能装在当前用户下。 「给这台机器所有用户装一份 Python」这个能力被故意去掉了，装的时候不会问你要不要 per-machine。公司里那种把运行时统一放在 C:\Program Files 下做镜像分发的场景，用它会别扭；真要做机器级部署，python.org 上还留了一个 .msi，无界面、按机器装、不带任何运行时，但要管理员权限。顺带一提，这个 MSI 也是 Windows Server 2019 上唯一的安装方式——它是目前唯一不支持 MSIX 的在支持列表里的系统。

pyenv-win 的版本覆盖不如 Linux 版。 它装的是预编译好的 zip 包，不走源码编译，装起来快，代价是个别补丁版本没有对应的包——pyenv install -l 里列着，真装的时候报找不到。要复现一个很老的项目，这点会让人上火。

pyenv-win 只接管裸的 python 命令。 py.exe、IDE 里配的解释器路径、脚本第一行的 shebang，它都不管。所以「命令行里 python --version 是 3.12，PyCharm 里跑起来还是 3.9」这种事很常见——不是它坏了，是它本来就没这个职责。官方这套对 shebang 是支持的，脚本第一行写 #! /usr/bin/python3.12，双击或直接执行时会挑对应的解释器，这个在 Windows 上省事不少。

还有一点不太算缺点但要心里有数：官方这套会把机器上没被它管理的 Python 一起列出来（配置项 include_unmanaged 默认开着），所以以前乱装过的解释器不会消失，只是标成 unmanaged。用 py list --only-managed 可以只看它自己装的。

升级也值得说一句：py install --update 会把解释器更新到最新补丁版，全局安装的包会被清掉，但虚拟环境不受影响，还能照常用。这个行为比想象中温和。

时间表

网上「3.16 之后 pyenv 就没了」这类说法是把两件事记串了，实际的时间线是这样：

传统那个 .exe 安装包和单独分发的 py 启动器，从 3.14 起在官方文档里被标为 deprecated，计划在 PEP 773 被接受后的两年内停止发布，也就是 2027 年 4 月前后不再有新版本；PEP 本身的目标是在 3.16 之前完成这个过渡。换句话说 3.15 大概是最后一个还带传统安装包的版本。离现在还有一年多，不用急着把老机器全迁一遍，但新装的机器没必要再走老路了。

至于 Python Install Manager 本身，目前只有 Windows 版本，只出 Intel 64 位的包，32 位系统用不了（32 位的 CPython 运行时倒是还能装）。跨平台支持、把依赖管理也包进来这些想法，都躺在 PEP 的 rejected ideas 里。

我现在的选择

新机器先 winget install 9NQ7512CXL7T -e，然后每个项目 python -m venv .venv，需要哪个版本就 py install 一下。这套流程里我不用记得 rehash，也不用担心 PATH 被改坏。

pyenv-win 在一台要跑老项目的机器上还留着，理由很朴素——没坏就先不动它。pyenv local 加 python -m venv 的组合也能过日子，只是每换一个版本就要记得 rehash 一次。

如果你的项目本身是跨平台的，CI 里 Linux 和 macOS 跑同一套脚本，那 pyenv 全家的跨平台一致性仍然是它最大的价值，Windows 上多受的这点罪算是买这张票的钱。

最后绕不开一句：这两年不少人的答案其实是 uv。装解释器、建虚拟环境、管依赖一条龙，Windows 上原生支持也好。它和本文这两个不是同一个层面的东西（官方那套是系统级的解释器管理，uv 更偏项目级，两者可以并存），但如果你只是想在一台机器上跑几个不同 Python 版本的项目，先试试 uv 可能比在这两个工具里挑更省事。

参考资料

• PEP 773 – A Python Installation Manager for Windows：https://peps.python.org/pep-0773/
• Python 官方文档 · Using Python on Windows（含 Python Install Manager 章节）：https://docs.python.org/3/using/windows.html
• pyenv-win 项目主页（安装与 FAQ）：https://github.com/pyenv-win/pyenv-win
• Microsoft Store 上的 Python Install Manager：https://apps.microsoft.com/detail/9nq7512cxl7t