使用 uv 管理多版本 python 共存的核心方法是利用其内置的 python 安装器功能,通过 uv python install 命令下载并注册不同版本的解释器,随后在项目中通过 uv sync --python 或设置 .python-version 文件来指定当前环境使用的具体版本。这样做可以让 uv 自动处理虚拟环境的创建与隔离,确保每个项目都能锁定到特定的 python 版本,而无需手动配置系统环境变量或依赖第三方工具如 pyenv。

如何安装并切换特定版本的 Python
要开始使用多版本共存,首先需要安装目标版本的 Python。uv 会自动从官方源下载对应操作系统的二进制包,并将其安装在本地缓存目录中,同时建立符号链接或注册表项以便系统识别。例如,运行 uv python install 3.10 和 uv python install 3.12 后,系统中就存在了两个可用的 Python 版本。接着,可以通过 uv python list 查看已安装的版本列表,并使用 uv run --python 3.10 <script></script> 临时指定版本运行脚本,或者在项目根目录创建 .python-version 文件写入 3.10,这样 uv sync 就会自动使用该版本创建虚拟环境。

uv python install 3.10 uv python install 3.12 uv python list mkdir myproject cd myproject uv init uv add requests uv sync --python 3.10 uv run python -c "import sys; print(sys.version)" uv sync --python 3.12 uv run python -c "import sys; print(sys.version)"
上述代码执行后,首先安装两个版本,然后初始化项目并添加依赖。第一次同步指定 3.10 版本,运行脚本输出应包含 3.10.x;第二次同步指定 3.12 版本,运行脚本输出应包含 3.12.x。这验证了 uv 能够根据参数切换底层解释器并创建独立的虚拟环境。
如何在项目中固定 Python 版本
在团队协作或 CI/CD 环境中,固定项目所使用的 Python 版本至关重要。uv 支持通过 .python-version 文件声明项目所需的最低或精确版本。当团队成员在项目目录下运行 uv sync 时,如果本地未安装指定版本,uv 会提示并询问是否自动安装,或者你可以预先通过 uv python install 准备好所有必要版本。这种方式比传统的 requirements.txt 更进了一步,因为它不仅管理包依赖,还直接管理解释器本身,消除了“在我机器上能跑”的环境差异问题。

# .python-version 3.11 # 终端命令 uv sync uv run python main.py
在这个场景中,.python-version 文件明确指定了 3.11。运行 uv sync 后,uv 会检查本地是否有 3.11 版本,若无则安装,若有则复用。随后 uv run 会在该版本创建的虚拟环境中执行 main.py。这种机制确保了开发、测试和生产环境的一致性,避免了因系统默认 Python 版本升级导致的兼容性问题。
基于 uv sync 命令的输入条件与结果分析
当在项目中执行 uv sync 命令时,其行为取决于当前目录是否存在 .python-version 文件以及是否通过命令行传入了 --python 参数。如果两者均未指定,uv 会使用系统默认找到的第一个可用 Python 版本。如果指定了 --python 3.10,即使存在 .python-version 文件,命令行参数通常具有更高优先级(具体行为可能随版本更新略有调整,但通常显式参数优先)。结果是,uv 会创建一个指向指定版本解释器的虚拟环境,并安装 pyproject.toml 中定义的依赖。若指定版本未安装,uv 会尝试自动下载,除非设置了 UV_PYTHON_DOWNLOADS=manual 环境变量。这一过程完全自动化,无需用户干预路径配置。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











