uv 是一款据称非常快速的 Python 包与项目管理器,资料称其可替代 pip、pip-tools、pipx、pyenv、virtualenv、poetry 等工具。本条目是面向智能体的 uv 使用指南插件,用于在涉及 Python 项目、脚本、包或工具时提供统一操作规范。
一、何时使用 建议所有 Python 工作都使用 uv,尤其当出现 uv.lock 文件,或 requirements* 文件中带有 uv 生成标记(如“This file was autogenerated by uv”)时。若项目由其他工具管理,则不应使用 uv,例如含 poetry.lock 的 Poetry 项目、含 pdm.lock 的 PDM 项目。
二、按场景选择工作流
- 脚本:适用于运行单个 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 sync --locked(要求锁文件为最新)、uv run <command>(在环境中运行命令)、uv run python -c ""(在项目环境中运行 Python)、uv run -p 3.12 <command>(指定 Python 版本运行)。
- 工具:项目内声明的工具用 uv run 调用,如 uv run pytest、uv run ruff check .,可复用项目锁定的工具版本并使其依赖可用;独立工具用 uvx 在隔离环境中运行,如 uvx <tool> <args>、uvx <tool>@<version> <args>。注意 uvx 按包名从 PyPI 运行工具,存在安全风险,只应运行知名工具;仅当用户明确要求时才使用 uv tool install。
三、类型检查 使用 uv check 通过 ty 对 uv 项目做类型检查:它会同步项目环境;当 ty 是项目依赖或 dev 依赖组成员时使用 uv.lock 中的版本,否则选择兼容版本。对于 PEP 723 脚本,使用 uv check --script script.py 结合其内联依赖进行检查。
四、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:应使用 uv add requests 而非 pip install requests。不要直接运行 python:应使用 uv run script.py 而非 python script.py;使用 uv run python -c "..." 而非 python -c "...";需要指定版本时使用 uv run --python 3.12 python -c "..." 而非 python3.12 -c "..."。当明确需要独立解释器时使用 uvx python@3.12。不要在 uv 项目中手动管理环境:应使用 uv run <command>,而非 python -m venv .venv 加 source .venv/bin/activate。
七、文档 更多细节可阅读官方文档:https://docs.astral.sh/uv/llms.txt ,该文档链接到各工作流的专门页面。