uv会读取pyproject.toml中的[tool.uv]段落，但仅在无uv.toml文件时生效；常见配置包括dev-dependencies、index-url和python-versions，不支持缓存路径等系统级参数。

pyproject.toml 中的 [tool.uv] 怎么写

uv 会读取 pyproject.toml 里的 [tool.uv] 段落，但**只在没有 uv.toml 文件时生效**。这个配置段适合项目级、轻量定制，比如指定 dev 依赖或默认 index。

常见写法示例：

• dev-dependencies = ["pytest", "ruff"]：声明开发依赖，uv add --dev 会自动写入这里
• index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"：覆盖全局镜像源，仅对当前项目生效
• python-versions = ["3.12"]：配合 uv lock 限制解析范围（不是运行时 Python 版本）

注意：[tool.uv] 不支持设置缓存路径、Python 安装目录等系统级参数——这些必须用环境变量或 uv.toml。

uv.toml 文件优先级和位置规则

一旦存在 uv.toml，它会完全屏蔽 pyproject.toml 中的 [tool.uv] 配置。它的查找顺序是：当前目录 → 逐级向上父目录 → 用户级（~/.config/uv/uv.toml）→ 系统级（/etc/uv/uv.toml）。

立即学习“Python免费学习笔记（深入）”；

典型内容（国内加速必备）：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

[pip]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[python]
install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"

关键点：

• Windows 上用户级路径是 %APPDATA%\uv\uv.toml，不是 %USERPROFILE% 下
• 文件名必须是 uv.toml，不是 .uv.toml 或 uv.config
• 修改后无需重启终端，但已有进程中的 uv 命令可能仍用旧缓存，建议新开 shell 验证

环境变量和 uv.toml 冲突时谁生效

环境变量优先级最高。例如你设了 UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple，同时 uv.toml 里写了清华源，最终生效的是阿里源。

常用环境变量与用途对应关系：

• UV_CACHE_DIR：强制缓存路径（避免 C 盘爆满）
• UV_PYTHON_INSTALL_DIR：指定 Python 解释器下载位置
• UV_DEFAULT_INDEX：全局 pip index，覆盖所有配置文件中的 index 设置
• UV_TOOL_DIR：存放 uvx 安装的 CLI 工具（如 black、isort）

验证是否生效，直接运行：uv cachedir、uv pythondir、uv tooldir。

为什么改了配置还是走默认 PyPI

最常见原因不是配置没写对，而是命令用错了。比如：

• 执行 uv pip install requests 时，uv 实际走的是 [pip] 段或 UV_DEFAULT_INDEX，而不是 [[index]] 列表
• 执行 uv add requests 时，才真正读 [[index]] 和 [tool.uv]
• uv python install 3.12 只认 [python].install-mirror，不看 index 配置

简单记：带 pip 子命令的，走 pip 风格配置；不带的（如 add、python install），走 uv 原生配置。混用时容易踩坑。