uv通过目录隔离识别项目，每个项目独享pyproject.toml；切换依赖环境需配合uv python pin指定python版本后执行uv sync重解析依赖树。

uv 如何识别并切换不同项目的 pyproject.toml

uv 本身不支持“多配置文件共存于同一目录”这种模式，它只读取当前工作目录下唯一的 pyproject.toml。但你完全可以通过目录隔离 + uv python pin + uv sync 实现项目级多环境配置。关键不是“一个配置文件切多个环境”，而是“每个项目带自己专属的配置”。

为什么 uv sync 有时不读 pyproject.toml 的 requires-python

常见错误现象：uv sync 报错 No Python version found that satisfies the project's requirements，即使 pyproject.toml 里写了 requires-python = ">=3.9,。

原因在于：uv 默认不会自动安装缺失的 Python 版本，它只检查已安装版本是否匹配约束。解决步骤如下：

• 先运行 uv python list 查看当前已安装哪些版本
• 若缺少符合 requires-python 的版本，手动安装：uv python install 3.11.9
• 再执行 uv sync，它就会基于已装版本做兼容性筛选
• 注意：uv venv --python 3.11 创建的环境，和 uv sync 所用的 Python 版本必须一致，否则锁文件可能不生效

如何让 uv 在不同项目中自动加载对应 Python 版本

靠 .python-version 文件驱动。在项目根目录执行：

uv python pin 3.11.9

会生成一个纯文本文件 .python-version，内容就是 3.11.9。之后只要你在该项目目录下运行：

Secure Python Code Sandbox

安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。

下载

• uv sync → 自动选用 3.11.9 解释器解析依赖
• uv run python --version → 输出 Python 3.11.9
• uv venv → 默认创建绑定 3.11.9 的 .venv

这个机制不依赖 shell 配置，也不需要 pyenv —— uv 自己读取该文件并调度本地已安装的对应版本。

pyproject.toml 中 tool.uv 配置项对多环境的影响

[tool.uv] 是 uv 的全局行为控制区，影响所有子命令。常见实用配置：

• index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"：指定镜像源，避免每个项目重复配置
• python-install-dir = "./.python"（不推荐）：强制把 Python 解释器装进项目目录 —— 这会让项目体积暴涨，且无法跨项目复用解释器；更合理做法是用 UV_PYTHON_INSTALL_DIR 环境变量统一管理
• no-cache = true：禁用 wheel 缓存，调试时有用，但会显著拖慢重复安装

真正影响多环境隔离的是 requires-python 和 dependencies 声明本身，[tool.uv] 只负责“怎么装”，不决定“装什么版本”。

最易被忽略的一点：uv 不会自动同步 .python-version 和 pyproject.toml 中的 requires-python。二者可以不一致 —— 前者决定实际运行用哪个解释器，后者仅用于依赖解析时的兼容性过滤。如果你改了 requires-python 却没更新 .python-version，uv sync 可能成功，但运行时直接报 ModuleNotFoundError，因为底层解释器版本不支持某个包的字节码。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！