uv 是一个速度极快的 Python 包与项目管理器，可替代 pip、pip-tools、pipx、pyenv、virtualenv、poetry 等工具。本条目是一份面向 Python 工作的 uv 使用指南。
适用时机 处理 Python 工作时优先使用 uv，尤其是出现以下信号时：存在 uv.lock 文件；requirements* 文件带有 uv 生成头部（如“This file was autogenerated by uv”）。若项目由其他工具管理，则不要使用 uv，例如 Poetry 项目（以 poetry.lock 标识）和 PDM 项目（以 pdm.lock 标识）。
工作流一：脚本 适用于运行单个 Python 文件和独立脚本。常用命令：
- uv run script.py：运行脚本
- uv run --with requests script.py：附带额外包运行
- uv add --script script.py requests：向脚本内联添加依赖
工作流二：项目 适用于存在 pyproject.toml 或 uv.lock 的情况。常用命令：
- uv init：创建新项目
- uv add requests：添加依赖
- uv remove requests：移除依赖
- uv sync：按锁文件安装
- uv run <command>：在项目环境中运行命令
- uv run python -c ""：在项目环境中运行 Python
- uv run -p 3.12 <command>：以指定 Python 版本运行
工作流三：工具 适用于无需安装即可运行命令行工具（如 ruff、ty、pytest）。常用命令：
- uvx <tool> <args>：不安装直接运行工具
- uvx <tool>@<version> <args>：运行指定版本的工具 注意事项：uvx 按包名从 PyPI 运行工具，可能存在安全风险，只应运行知名工具；仅当用户明确要求时才使用 uv tool install。
工作流四：pip 接口 适用于使用 requirements.txt 或需要手动管理环境的遗留工作流，且没有 uv.lock。常用命令：
- uv venv
- uv pip install -r requirements.txt
- uv pip compile requirements.in -o requirements.txt
- uv pip sync requirements.txt
- uv pip compile --universal requirements.in -o requirements.txt（平台无关解析） 注意事项：除非确有需要，否则不要使用 pip 接口；不要引入新的 requirements.txt 文件；新项目优先使用 uv init。
从其他工具迁移 pyenv 到 uv python：
- pyenv install 3.12 → uv python install 3.12
- pyenv versions → uv python list --only-installed
- pyenv local 3.12 → uv python pin 3.12
- pyenv global 3.12 → uv python install 3.12 --default
pipx 到 uvx：
- pipx run ruff → uvx ruff
- pipx install ruff → uv tool install ruff
- pipx upgrade ruff → uv tool upgrade ruff
- pipx list → uv tool list
pip 与 pip-tools 到 uv pip：
- pip install package → uv pip install package
- pip install -r req.txt → uv pip install -r req.txt
- pip freeze → uv pip freeze
- pip-compile req.in → uv pip compile req.in
- pip-sync req.txt → uv pip sync req.txt
- virtualenv .venv → uv venv
常见模式（应避免的做法与替代写法）
- 不要在 uv 项目中用 pip：pip install requests 应改为 uv add requests
- 不要直接运行 python：python script.py 应改为 uv run script.py；python -c "..." 应改为 uv run python -c "..."；python3.12 -c "..." 应改为 uvx python@3.12 -c "..."
- 不要在 uv 项目中手动管理环境：python -m venv .venv 加 source .venv/bin/activate 应改为 uv run <command>
文档 详细资料见官方文档 https://docs.astral.sh/uv/llms.txt，该文档为各工作流链接到具体页面。