uv

uv

uv 是一个速度极快的 Python 包和项目管理器。它可以替代 pip、 pip-tools、pipx、pyenv、virtualenv、poetry 等工具。

何时使用 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                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add dependencies inline to the script

项目

适用场景： 存在 pyproject.toml 或 uv.lock

关键命令：

uv init                   # Create new project
uv add requests           # Add dependency
uv remove requests        # Remove dependency
uv sync                   # Install from lockfile
uv run <command>          # Run commands in environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version

工具

适用场景： 无需安装即可运行命令行工具（例如 ruff、ty、pytest）。

关键命令：

uvx <tool> <args>            # Run a tool without installation
uvx <tool>@<version> <args>  # Run a specific version of a tool

重要提示：

• 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

# Platform independent resolution
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

# Bad
pip install requests

# Good
uv add requests

不要直接运行 python

# Bad
python script.py

# Good
uv run script.py

# Bad
python -c "..."

# Good
uv run python -c "..."

# Bad
python3.12 -c "..."

# Good
uvx [email protected] -c "..."

不要在 uv 项目中手动管理环境

# Bad
python -m venv .venv
source .venv/bin/activate

# Good
uv run <command>

文档

如需详细信息，请阅读官方文档：

• https://docs.astral.sh/uv/llms.txt

文档中提供了指向上述各类工作流对应页面的链接。