uv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

uv

uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, pyenv, virtualenv, poetry, etc.

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

When to use uv

何时使用uv

Always use uv for Python work, especially if you see:

The
```
uv.lock
```
file
uv headers in
```
requirements*
```
files, e.g., "This file was autogenerated by uv"

Don't use uv in projects managed by other tools:

Poetry projects (identifiable by
```
poetry.lock
```
file)
PDM projects (identifiable by
```
pdm.lock
```
file)

Python开发工作中应优先使用uv，尤其是出现以下情况时：

存在
```
uv.lock
```
文件
```
requirements*
```
文件中包含uv头部信息，例如："This file was autogenerated by uv"

请勿在由其他工具管理的项目中使用uv：

Poetry项目（可通过
```
poetry.lock
```
文件识别）
PDM项目（可通过
```
pdm.lock
```
文件识别）

Choosing the right workflow

选择合适的工作流

Scripts

脚本场景

Use when: Running single Python files and standalone scripts.

Key commands:

bash

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

适用场景： 运行单个Python文件或独立脚本。

核心命令：

bash

uv run script.py                      # 运行脚本
uv run --with requests script.py      # 附加依赖包运行脚本
uv add --script script.py requests    # 为脚本内联添加依赖

Projects

项目场景

Use when: There is a

pyproject.toml

uv.lock

Key commands:

bash

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

适用场景： 项目中存在

pyproject.toml

或

uv.lock

文件

核心命令：

bash

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版本运行命令

Tools

工具场景

Use when: Running command-line tools (e.g., ruff, ty, pytest) without installation.

Key commands:

bash

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

Important:

```
uvx
```
runs tools from PyPI by package name. This can be unsafe - only run well-known tools.
Only use
```
uv tool install
```
only when specifically requested by the user.

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

核心命令：

bash

uvx <tool> <args>            # 无需安装直接运行工具
uvx <tool>@<version> <args>  # 运行工具的指定版本

注意事项：

```
uvx
```
通过包名称从PyPI运行工具，存在安全风险——仅运行知名工具。
仅在用户明确要求时使用
```
uv tool install
```
。

Pip interface

Pip兼容接口

Use when: Legacy workflows with

requirements.txt

or manual environment management, no

uv.lock

present.

Key commands:

bash

uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

适用场景： 依赖

requirements.txt

的遗留工作流或手动环境管理，且无

uv.lock

文件。

核心命令：

bash

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


**Important:**

- Don't use the pip interface unless clearly needed.
- Don't introduce new `requirements.txt` files.
- Prefer `uv init` for new projects.

uv pip compile --universal requirements.in -o requirements.txt


**注意事项：**

- 除非明确需要，否则不要使用pip兼容接口。
- 不要新建`requirements.txt`文件。
- 新项目优先使用`uv init`。

Migrating from other tools

从其他工具迁移

pyenv → uv python

bash

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

bash

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

bash

pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list

bash

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 and pip-tools → uv pip

pip 和 pip-tools → uv pip

bash

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

bash

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

Common patterns

通用规范

Don't use pip in uv projects

不要在uv项目中使用pip

bash

undefined

bash

undefined

Bad

错误做法

pip install requests

Good

正确做法

uv add requests

undefined

uv add requests

undefined

Don't run python directly

不要直接运行python

bash

undefined

bash

undefined

Bad

错误做法

python script.py

Good

正确做法

uv run script.py


```bash

uv run script.py


```bash

Bad

错误做法

python -c "..."

Good

正确做法

uv run python -c "..."


```bash

uv run python -c "..."


```bash

Bad

错误做法

python3.12 -c "..."

Good

正确做法

uvx python@3.12 -c "..."

undefined

uvx python@3.12 -c "..."

undefined

Don't manually manage environments in uv projects

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

bash

undefined

bash

undefined

Bad

错误做法

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

Good

正确做法

uv run <command>

undefined

uv run <command>

undefined

Documentation

文档参考

For detailed information, read the official documentation:

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

The documentation links to specific pages for each of these workflows.

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

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

该文档包含上述各工作流的具体页面链接。