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

uv

Original

Translation

uv

uv

When to use uv

何时使用uv

Choosing the right workflow

选择合适的工作流程

Scripts

脚本场景

Projects

项目场景

Tools

工具场景

Pip interface

Pip接口场景

Platform independent resolution

跨平台依赖解析

Migrating from other tools

从其他工具迁移

pyenv → uv python

pyenv → uv python

pipx → uvx

pipx → uvx

pip and pip-tools → uv pip

pip 和 pip-tools → uv pip

Common patterns

常见规范

Don't use pip in uv projects

不要在uv项目中使用pip

Bad

不推荐

Good

推荐

Don't run python directly

不要直接运行python命令

Bad

不推荐

Good

推荐

Bad

不推荐

Good

推荐

Bad

不推荐

Good

推荐

Don't manually manage environments in uv projects

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

Bad

不推荐

Good

推荐

Documentation

文档