Windows 安装 uv 方法

安装

winget install --id=astral-sh.uv -e

当使用 uv add 安装软件包时提示 No pyproject.toml found，说明当前目录或父级目录中缺少 Python 项目配置文件。以下是综合多篇指南的解决方案：

---

一、根本原因解析

uv add 是面向 项目管理 的命令，其核心逻辑是通过 pyproject.toml 文件记录依赖关系（类似 poetry 工具）。如果未检测到此文件，会认为当前不属于任何项目，因此报错。

---

二、解决方案

1. 初始化新项目（推荐）

在项目根目录执行：

uv init .  # 注意末尾的"."表示当前目录

该命令会生成以下文件：

• pyproject.toml：项目元数据文件
• .python-version：Python 版本约束文件
• uv.lock：依赖锁文件（自动生成）

验证：完成后再次运行 uv add 包名 即可正常安装依赖。

---

2. 手动创建 pyproject.toml

如果已有项目结构但缺少配置文件，可手动创建：

# pyproject.toml
[project]
name = "your_project"
version = "0.1.0"
requires-python = ">=3.8"
dependencies = []

保存后执行 uv sync 同步环境，再使用 uv add。

---

3. 指定配置文件路径（多项目场景）

如果配置文件存在于非当前目录：

uv add 包名 --project /path/to/project

或通过环境变量指定：

export UV_PROJECT_PATH=/path/to/project
uv add 包名

---

4. 检查目录层级

通过 uv add --verbose 查看 uv 搜索 pyproject.toml 的路径：

uv add 包名 --verbose
# 输出会显示搜索路径，如：
# Searching for pyproject.toml in /current/dir -> /parent/dir -> ...

根据输出调整命令执行位置。

---

三、进阶场景

▶ 已有 requirements.txt 的项目

uv init --existing .  # 将现有项目转为 uv 管理
uv add -r requirements.txt  # 导入依赖
uv sync  # 同步环境

▶ 单文件脚本依赖管理

对于独立脚本（如 demo.py），可通过内联注释声明依赖：

# /// [uv]
# dependencies = ["requests"]
# ///

import requests
print(requests.get("https://astral.sh").status_code)

运行命令：

uv run demo.py  # 自动处理依赖

---

四、常见问题排查

• 文件位置错误：确保 pyproject.toml 位于项目根目录
• 文件内容错误：检查 TOML 语法是否合法（可用 uv check 验证）
• 权限问题：在 Linux/macOS 中，若目录权限不足，需 chmod +rw 授权

通过以上方法，可快速解决 uv add 的配置文件缺失问题。如果仍遇到问题，建议通过 uv --verbose 输出详细日志定位根源。