先明确需要管理哪一层
主要需要切换 Python 解释器,或者团队已经有成熟的 pyenv 工作流,可以继续使用 pyenv。还希望统一管理解释器、项目环境、依赖和锁文件时,可以考虑 uv。
二者都能参与版本选择,区别在于负责的工作范围。解释器版本与第三方包隔离是两个问题,不能把它们混为一谈。
pyenv 通过 shims 选择解释器
pyenv 将 shims 放到 PATH 前部,再把 python 等命令转发给选中的解释器。常规选择顺序是 PYENV_VERSION 环境变量、当前目录或父目录中的 .python-version,最后是全局设置。
pyenv versions
pyenv local 3.12.8
python --version
示例要求该版本已经安装;这里的补丁版本仅用于演示,应按项目要求选择仍受支持的版本。pyenv 的核心机制不是切换动态链接库,也不负责自动隔离第三方依赖。
虚拟环境可以通过标准库 venv 创建,或使用另行安装的 pyenv-virtualenv 插件。pyenv virtualenv 不是基础 pyenv 自带的命令。
uv 管理项目环境和依赖
uv 是 Astral 开发的 Rust 实现的 Python 包与项目管理工具。它可以安装受支持的 Python 构建、创建环境、解析依赖并运行项目命令。
项目工作流围绕 pyproject.toml、uv.lock 和 .venv 展开。.python-version 可以固定所需解释器,而 requires-python 声明项目兼容范围,两者含义不同。具体规则见 Python 版本文档。
安装后先确认实际命令路径
pyenv 的系统依赖和 Shell 初始化应按官方安装说明配置。Linux 上从源码构建解释器需要相应开发库,Bash 与 Zsh 的启动文件也不同。Windows 应按项目的平台说明选择方案。
uv 使用官方安装指南提供的对应方式。安装完成后检查:
command -v python
python --version
uv --version
安装工具不会必然改变已有终端、编辑器或项目选中的解释器。路径与版本检查比反复重装更容易定位冲突。
保留已有 pyenv 工作流
选择项目所需解释器后,可以创建标准虚拟环境:
python -m venv .venv
source .venv/bin/activate
python -m pip --version
这里是 POSIX Shell 的激活命令,Windows 应使用对应命令。依赖安装继续遵循项目既有的 requirements 或打包工具约定。
用 uv 创建项目
在新目录执行:
uv init --python 3.12
uv add requests
uv run python --version
uv run python -c 'import requests; print(requests.__version__)'
3.12 是示例次版本,并非当前最新版的声明。uv init 创建项目元数据与初始文件,不会扫描已有源码并自动推断全部依赖;uv add 显式声明依赖。运行 uv sync 或 uv run 等项目命令时,uv 按需要创建或更新 .venv。
用锁文件复现环境
将 pyproject.toml 与 uv.lock 提交到版本库,忽略 .venv。在锁文件已更新的 checkout 中执行:
uv sync --locked
uv run --locked python --version
--locked 在锁文件需要更新时失败,而不是悄悄改动解析结果。需要主动更新解析时使用 uv lock。项目操作见官方项目指南。
旧文中的 uv install、uv shell 和 uv shell npm run dev 已移除;项目内运行命令使用 uv run,也可以通过 Shell 的常规方式激活 .venv。
功能对比
| 需求 | pyenv | uv |
|---|---|---|
| 解释器选择 | shims 与版本设置 | Python 发现、版本请求与项目固定 |
| 安装 Python | 常通过 python-build 构建 | 安装受支持的托管 Python 构建 |
| 环境隔离 | 配合 venv 或其他工具、插件 | 项目 .venv 或 uv venv |
| 依赖解析与锁定 | 使用单独的包管理工具 | uv add、uv lock、uv sync |
| 项目内运行 | 激活环境后运行 | uv run |
uv 的 pip 兼容接口与项目接口用途不同。需要让锁文件准确描述项目依赖时,不要随意混用临时安装与项目依赖声明,详见环境参考。
适用场景
既有测试矩阵、Shell 约定或源码构建要求可能适合保留 pyenv。希望统一新应用的本地与 CI 环境时,可以采用 uv 项目工作流。
两者可以共存,但要显式核对解释器。项目外的 python --version 不代表 uv run python --version 一定相同。
性能比较要测同一件事
从源码安装解释器和从缓存同步依赖不是同一种操作。网络、缓存、wheel 可用性、平台和依赖规模都会影响耗时。本文没有受控基准测试,不给出固定倍数或“启动一定更快”的结论。
取舍与约束
pyenv 将解释器选择与包管理分开,便于保留团队已有工具,但需要维护多个环节。uv 将更多工作放入项目流程,团队也需要统一锁文件更新和 CI 命令。
更换 Python 次版本之前,检查原生扩展和部署平台兼容性。锁文件能够帮助复现解析结果,无法使不支持的平台或解释器变得兼容。
迁移检查步骤
- 记录当前 Python 版本、依赖文件、测试命令和部署环境。
- 在独立分支或临时 checkout 中尝试 uv,明确声明依赖,不复制旧虚拟环境。
- 使用目标解释器验证应用测试与实际行为。
- 一起更新本地说明和 CI,再提交元数据及锁文件。
仅需要版本选择时可以保留 pyenv;uv 的项目管理流程能减少实际维护工作时再迁移。本文命令与参考于 2026 年 10 月 16 日核对,不代表任何具体应用已经完成迁移验收。