---

name: python-env description: "使用 uv 进行快速 Python 环境管理（比 pip 快 10-100 倍）。触发条件：uv、venv、pip、pyproject、python environment、install package、dependencies。" license: MIT compatibility: "需要 uv CLI 工具。安装：curl -LsSf https://astral.sh/uv/install.sh | sh" allowed-tools: "Bash" metadata: author: claude-mods

Python 环境

使用 uv 进行快速 Python 环境管理。优先使用 uv 项目工作流（uv add / uv sync / uv run）而非 uv pip 兼容层——它为你管理 pyproject.toml + 锁文件，且可复现。

快速命令

| 任务 | 命令 | |------|---------| | 创建项目 | uv init <name>（应用）· uv init --package <name>（可安装包，src/ 布局） | | 添加依赖 | uv add httpx | | 添加开发依赖 | uv add --dev pytest ruff | | 移除依赖 | uv remove httpx | | 从锁文件同步环境 | uv sync | | 在项目环境中运行 | uv run pytest | | 更新锁文件 | uv lock | | 安装 CLI 工具 | uv tool install ruff · 一次性：uvx ruff | | 安装 Python | uv python install 3.12 |

创建项目

# Application (flat layout, no package build)
uv init myapp

# Installable package (src/ layout)
uv init --package wordtools

uv init 创建 pyproject.toml，固定 Python 版本，并为 uv add / uv sync 准备项目。--package（src）布局适用于有测试套件或需要发布的项目。

管理依赖

# 添加运行时依赖（写入 [project.dependencies] + 更新锁文件）
uv add "httpx>=0.25" pydantic

# 添加仅开发依赖（写入 dev 依赖组）
uv add --dev pytest ruff mypy

# 添加带 extras 的包
uv add "fastapi[standard]"

# 移除
uv remove httpx

# 从 pyproject + uv.lock 安装所有内容到 .venv（可复现）
uv sync

# 刷新锁文件（如手动编辑 pyproject 后）
uv lock

uv 自动创建和管理 .venv——你很少需要激活它；只需在命令前加 uv run。

运行代码

uv run python script.py     # 在项目环境中运行脚本
uv run pytest               # 运行 dev 组中的工具
uv run -- ruff check .      # -- 结束 uv 标志解析

在 uv 项目中永远不要直接调用 python / pytest / ruff——它们可能解析到不同的解释器。始终使用 uv run。

CLI 工具（全局，非项目依赖）

uv tool install ruff        # 持久化、隔离、在 PATH 上
uv tool upgrade ruff
uvx ruff check .            # 临时一次性运行，不安装

使用 uv tool / uvx 安装开发者 CLI（ruff、pre-commit、httpie）。仅对代码导入的包使用 uv add。

Python 版本

uv python install 3.12      # 下载托管解释器
uv python list              # 显示可用 + 已安装
uv init --python 3.12 app   # 将项目固定到某版本

最小 pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.25",
    "pydantic>=2.0",
]

[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

兼容层（uv pip）——最后手段

uv pip 模拟 pip 的接口，用于 uv 不管理的环境。它不会更新 pyproject.toml 或锁文件——尽可能使用 uv add / uv sync。

uv venv                              # 裸 venv（无项目）
uv pip install -r requirements.txt   # 旧式 requirements 文件
uv pip install -e .                  # 可编辑安装到非托管 venv
uv pip compile requirements.in -o requirements.txt   # 固定 requirements.txt

故障排除

| 问题 | 解决方案 | |-------|----------| | "No Python found" | uv python install 3.12 | | 固定项目 Python | uv init --python 3.12 或编辑 requires-python | | 锁/解析冲突 | uv lock --resolution=lowest-direct 探测，然后放宽约束 | | pull 后环境过期 | uv sync | | 缓存问题 | uv cache clean |

何时使用

• 始终使用 uv 代替 pip——快 10-100 倍
• uv add / uv remove / uv sync 管理项目依赖（不是 uv pip install）
• uv run 在项目环境中执行任何命令
• uv tool install / uvx 安装独立开发者 CLI
• uv pip 仅用于 uv 不管理的环境

附加资源

• ./references/pyproject-patterns.md - 完整 pyproject.toml 示例、工具配置
• ./references/dependency-management.md - 锁文件、工作区、私有包