uv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

uv Package Manager

uv包管理器

Prefer uv over pip/poetry for Python dependency and project management. Use the workflow below and choose the right mode (project, script, or tool).

在Python依赖和项目管理中，优先选择uv而非pip/poetry。请遵循以下工作流，并选择合适的模式（项目、脚本或工具）。

Mode Decision

模式选择

User needs to...
│
├─ Repo uses poetry / pipenv / conda (poetry.lock, Pipfile, environment.yml)
│  → Ask: "This repo uses [poetry/pipenv/conda]. Do you want to switch to uv?"
│  → If yes: prefer the migrate-to-uv tool (uvx migrate-to-uv in project root) to convert metadata and lockfile; then uv sync. Remove legacy files only after user confirms.
│  → If no: do not use uv for project management; use the existing tool or uv pip only if appropriate.
│
├─ Repo has requirements.txt (no pyproject.toml)
│  → Ask: "This repo uses requirements.txt. Do you want to convert to uv (pyproject.toml + uv.lock)?"
│  → If yes: guide conversion (uv init, uv add from requirements, then uv sync)
│  → If no: use Pip-Compatible workflow (uv pip)
│
├─ Manage a project (pyproject.toml, lockfile, team repo)
│  → Use PROJECT workflow (uv init, uv add, uv sync, uv run)
│
├─ Run a single script with dependencies
│  → Use SCRIPT workflow (uv add --script, uv run <script>)
│
├─ Run a one-off CLI tool (no project)
│  → Use uvx: uvx <package> [args] or uv tool install <package>
│
└─ User declined conversion; existing pip/requirements workflow
   → Use uv pip (uv venv, uv pip sync, uv pip compile)

User needs to...
│
├─ Repo uses poetry / pipenv / conda (poetry.lock, Pipfile, environment.yml)
│  → Ask: "This repo uses [poetry/pipenv/conda]. Do you want to switch to uv?"
│  → If yes: prefer the migrate-to-uv tool (uvx migrate-to-uv in project root) to convert metadata and lockfile; then uv sync. Remove legacy files only after user confirms.
│  → If no: do not use uv for project management; use the existing tool or uv pip only if appropriate.
│
├─ Repo has requirements.txt (no pyproject.toml)
│  → Ask: "This repo uses requirements.txt. Do you want to convert to uv (pyproject.toml + uv.lock)?"
│  → If yes: guide conversion (uv init, uv add from requirements, then uv sync)
│  → If no: use Pip-Compatible workflow (uv pip)
│
├─ Manage a project (pyproject.toml, lockfile, team repo)
│  → Use PROJECT workflow (uv init, uv add, uv sync, uv run)
│
├─ Run a single script with dependencies
│  → Use SCRIPT workflow (uv add --script, uv run <script>)
│
├─ Run a one-off CLI tool (no project)
│  → Use uvx: uvx <package> [args] or uv tool install <package>
│
└─ User declined conversion; existing pip/requirements workflow
   → Use uv pip (uv venv, uv pip sync, uv pip compile)

Project Workflow

项目工作流

Use for apps, libraries, or any repo with

pyproject.toml

适用于应用程序、库或任何包含

pyproject.toml

的仓库。

New project

新项目

bash

uv init [project-name]
cd [project-name]
uv add <package> [package2...]
uv sync
uv run python main.py

bash

uv init [project-name]
cd [project-name]
uv add <package> [package2...]
uv sync
uv run python main.py

or: uv run <any command>

undefined

undefined

Existing project (already has pyproject.toml)

现有项目（已包含pyproject.toml）

bash

uv sync                    # install from lockfile (or resolve and lock)
uv add <package>           # add dependency, update lockfile and env
uv remove <package>       # remove dependency
uv run <command>          # run in project venv (creates .venv if needed)
uv lock                   # refresh lockfile only

bash

uv sync                    # install from lockfile (or resolve and lock)
uv add <package>           # add dependency, update lockfile and env
uv remove <package>       # remove dependency
uv run <command>          # run in project venv (creates .venv if needed)
uv lock                   # refresh lockfile only

Pin Python version (optional)

固定Python版本（可选）

bash

uv python pin 3.11        # writes .python-version
uv python install 3.11    # ensure that version is available

Rules:

Use
```
uv add
```
for project dependencies; avoid editing
```
pyproject.toml
```
by hand for deps when uv can do it.
After changing dependencies, run
```
uv sync
```
(or rely on
```
uv add
```
/
```
uv remove
```
which update the env).
Run project commands via
```
uv run
```
so the correct venv and env are used; do not assume
```
pip install
```
or manual activate.
When creating a new project, ensure
```
.venv
```
is in
```
.gitignore
```
(uv init usually adds it; add it if missing).
Treat
```
uv.lock
```
as a mandatory source-controlled artifact: commit it so all environments and CI use the same dependency versions; the lockfile is universal (one file for Windows, macOS, Linux).

bash

uv python pin 3.11        # writes .python-version
uv python install 3.11    # ensure that version is available

规则：

项目依赖使用
```
uv add
```
命令添加；当uv可以完成依赖管理时，避免手动编辑
```
pyproject.toml
```
。
修改依赖后，运行
```
uv sync
```
（或依赖
```
uv add
```
/
```
uv remove
```
命令，它们会自动更新环境）。
通过
```
uv run
```
运行项目命令，确保使用正确的虚拟环境和配置；不要假设用户已执行
```
pip install
```
或手动激活虚拟环境。
创建新项目时，确保
```
.venv
```
已添加到
```
.gitignore
```
中（uv init通常会自动添加；如果缺失则手动添加）。
将
```
uv.lock
```
视为必须纳入版本控制的文件：提交它以确保所有环境和CI使用相同的依赖版本；该锁文件是跨平台的（Windows、macOS、Linux通用）。

Script Workflow

脚本工作流

For a single Python file that needs packages (no full project).

Add inline script metadata (or use
```
uv add --script
```
to add deps to the file):

python

undefined

适用于需要依赖包的单个Python文件（非完整项目）。

添加内联脚本元数据（或使用
```
uv add --script
```
命令向文件添加依赖）：

python

undefined

/// script

requires-python = ">=3.10"

dependencies = ["requests"]

///

import requests print(requests.get("https://example.com"))


2. Add deps from CLI (updates the script file):

```bash
uv add --script example.py requests

Run with uv (creates an ephemeral env if needed):

bash

uv run example.py

For executable scripts that run without typing

uv run

, use a shebang (PEP 723):

python

#!/usr/bin/env -S uv run --script

import requests print(requests.get("https://example.com"))


2. 通过CLI添加依赖（会更新脚本文件）：

```bash
uv add --script example.py requests

使用uv运行脚本（必要时会创建临时环境）：

bash

uv run example.py

对于无需输入

uv run

即可直接运行的可执行脚本，使用shebang（符合PEP 723规范）：

python

#!/usr/bin/env -S uv run --script

/// script

requires-python = ">=3.10"

dependencies = ["requests"]

///


**Rules:**

- Use `uv add --script <file>` to declare dependencies for that script.
- Use `uv run <script>.py` to run it; do not tell the user to `pip install` first.
- For portability, scripts can use shebang `#!/usr/bin/env -S uv run --script`.


**规则：**

- 使用`uv add --script <file>`为指定脚本声明依赖。
- 使用`uv run <script>.py`运行脚本；不要告知用户先执行`pip install`。
- 为了可移植性，脚本可使用shebang：`#!/usr/bin/env -S uv run --script`。

Tools (one-off CLI from PyPI)

工具模式（来自PyPI的一次性CLI工具）

Run without installing globally:

bash

uvx <package> [args]

无需全局安装即可运行：

bash

uvx <package> [args]

e.g. uvx ruff check .

e.g. uvx pycowsay "hello"


Install the tool for repeated use:

```bash
uv tool install <package>


安装工具以便重复使用：

```bash
uv tool install <package>

e.g. uv tool install ruff


**Rules:**

- Prefer `uvx` for one-off runs; use `uv tool install` when the user will call the tool often.


**规则：**

- 一次性运行优先使用`uvx`；当用户需要频繁调用工具时，使用`uv tool install`。

Repos Using requirements.txt

使用requirements.txt的仓库

When the repo has requirements.txt (and no

pyproject.toml

Ask the user: "This repo uses requirements.txt. Do you want to convert to uv (pyproject.toml + uv.lock)?"
If yes: Guide conversion:
```
uv init
```
, then
```
uv add -r requirements.txt
```
(or, if you have requirements.in and locked requirements.txt,
```
uv add -r requirements.in -c requirements.txt
```
to preserve versions), then
```
uv sync
```
. Optionally remove or keep requirements.txt per user preference.
If no: Use the Pip-Compatible workflow below (no conversion).

Do not convert to uv without asking when the repo currently uses only requirements.txt.

当仓库仅包含requirements.txt（无

pyproject.toml

）时：

询问用户： "该仓库使用requirements.txt。是否要转换为uv（pyproject.toml + uv.lock）？"
如果用户同意： 引导转换：执行
```
uv init
```
，然后
```
uv add -r requirements.txt
```
（如果有requirements.in和已锁定的requirements.txt，使用
```
uv add -r requirements.in -c requirements.txt
```
以保留版本），再执行
```
uv sync
```
。可根据用户偏好选择保留或删除requirements.txt。
如果用户不同意： 使用以下兼容Pip的工作流（不转换）。

当仓库当前仅使用requirements.txt时，请勿未经询问就转换为uv。

Pip-Compatible Workflow

兼容Pip的工作流

For repos that still use

requirements.txt

pip

(and user did not want conversion):

bash

uv venv                           # create .venv
uv pip sync requirements.txt      # install from locked requirements
uv pip compile requirements.in -o requirements.txt  # compile/lock

Use

uv pip

instead of

pip

for the same commands when you want speed and better resolution.

适用于仍使用

requirements.txt

或

pip

的仓库（且用户不同意转换）：

bash

uv venv                           # create .venv
uv pip sync requirements.txt      # install from locked requirements
uv pip compile requirements.in -o requirements.txt  # compile/lock

当你追求速度和更优的依赖解析时，使用

uv pip

替代

pip

执行相同命令。

CI and Docker

CI与Docker中的使用

When the user asks about uv in CI (e.g. GitHub Actions) or uv in Docker, advise using the patterns below and point to references/docker-and-ci.md for full detail.

CI (e.g. GitHub Actions):

Install uv with the official
```
astral-sh/setup-uv
```
action; use cache keyed by
```
uv.lock
```
and
```
pyproject.toml
```
.
Run
```
uv sync --locked
```
so the job fails if the lockfile is out of sync (no silent deploy of untested deps).
Optionally run
```
uv cache prune --ci
```
at end of job to keep cache lean.

Docker:

Use a multi-stage build: builder stage with
```
ghcr.io/astral-sh/uv
```
, copy only
```
uv.lock
```
and
```
pyproject.toml
```
first, run
```
uv sync
```
(or equivalent), then copy
```
.venv
```
and app code into a slim runtime image (no uv/Rust in final image).
Set
```
UV_COMPILE_BYTECODE=1
```
and
```
UV_LINK_MODE=copy
```
in the build stage; use
```
--no-editable
```
when syncing so the final image doesn’t depend on source.
Run the container as a non-root user when possible.

For step-by-step Dockerfiles and CI workflow examples, see references/docker-and-ci.md.

当用户询问CI中的uv（如GitHub Actions）或Docker中的uv时，建议使用以下模式，并指向references/docker-and-ci.md获取详细内容。

CI（如GitHub Actions）：

使用官方
```
astral-sh/setup-uv
```
Action安装uv；使用以
```
uv.lock
```
和
```
pyproject.toml
```
为键的缓存。
运行
```
uv sync --locked
```
，这样如果锁文件与配置不同步，任务会失败（避免静默部署未测试的依赖）。
可选：在任务结束时运行
```
uv cache prune --ci
```
以精简缓存。

Docker：

使用多阶段构建：构建阶段使用
```
ghcr.io/astral-sh/uv
```
镜像，先仅复制
```
uv.lock
```
和
```
pyproject.toml
```
，运行
```
uv sync
```
（或等效命令），然后将
```
.venv
```
和应用代码复制到轻量级运行时镜像（最终镜像中不含uv/Rust）。
在构建阶段设置
```
UV_COMPILE_BYTECODE=1
```
和
```
UV_LINK_MODE=copy
```
；同步时使用
```
--no-editable
```
参数，确保最终镜像不依赖源代码。
尽可能以非root用户运行容器。

如需分步Dockerfile和CI工作流示例，请查看references/docker-and-ci.md。

IDE Setup (Use uv .venv)

IDE配置（使用uv的.venv）

After uv creates or uses a project

.venv

, automatically try to configure the IDE to use that interpreter so run/debug and IntelliSense use the same environment.

Target: Workspace settings (project-scoped, shareable):
```
.vscode/settings.json
```

Setting:

python.defaultInterpreterPath

pointing at the project’s

.venv

Linux/macOS:
```
"${workspaceFolder}/.venv/bin/python"
```

Windows:

"${workspaceFolder}/.venv/Scripts/python.exe"

Behavior: If
```
.vscode/settings.json
```
exists, read it, add or update only
```
python.defaultInterpreterPath
```
, then write back. If it doesn’t exist, create
```
.vscode/
```
and the file with this setting. Preserve all other keys.
When: After
```
uv init
```
,
```
uv sync
```
, or conversion from requirements.txt that creates/updates
```
.venv
```
.

Rules:

Use workspace settings (
```
.vscode/settings.json
```
), not user settings, so the choice is per-project and can be committed.
Do not overwrite or remove other settings in the file.
If the workspace already has a Python interpreter selected, still add/update this key so the project’s
```
.venv
```
is the default.

当uv创建或更新项目的

.venv

后，自动尝试配置IDE使用该解释器，确保运行/调试和智能感知使用相同环境。

目标： 工作区设置（项目级，可共享）：
```
.vscode/settings.json
```

设置项：

python.defaultInterpreterPath

指向项目的

.venv

：

Linux/macOS：
```
"${workspaceFolder}/.venv/bin/python"
```

Windows：

"${workspaceFolder}/.venv/Scripts/python.exe"

操作： 如果
```
.vscode/settings.json
```
已存在，读取文件，仅添加或更新
```
python.defaultInterpreterPath
```
，然后写回。如果文件不存在，创建
```
.vscode/
```
目录和该文件并添加此设置。保留所有其他配置项。
时机： 在
```
uv init
```
、
```
uv sync
```
或从requirements.txt转换后创建/更新
```
.venv
```
时执行。

规则：

使用工作区设置（
```
.vscode/settings.json
```
）而非用户设置，确保配置是项目级的且可提交。
不要覆盖或删除文件中的其他设置。
如果工作区已选择Python解释器，仍需添加/更新此配置项，使项目的
```
.venv
```
成为默认解释器。

Automation and Agent Behavior

自动化与Agent行为规范

New Python project: Run
```
uv init
```
(or
```
uv init <name>
```
), then
```
uv add
```
for initial deps, then
```
uv sync
```
. Suggest
```
uv run
```
for run/test commands.
Add dependency: Use
```
uv add <package>
```
. For dev/optional:
```
uv add --dev <package>
```
.
Run something: Use
```
uv run <command>
```
in a project;
```
uv run script.py
```
for scripts;
```
uvx <tool>
```
for one-off tools.
No manual venv activate: Prefer
```
uv run
```
so the agent and user don’t depend on
```
source .venv/bin/activate
```
.
Lockfile: Commit
```
uv.lock
```
; treat it as mandatory for parity. After pull or after editing deps, run
```
uv sync
```
. In CI, use
```
uv sync --locked
```
so the job fails if the lockfile is out of sync with
```
pyproject.toml
```
.
Detecting uv: If
```
pyproject.toml
```
exists and there is no poetry/pipenv/conda (no poetry.lock, Pipfile, environment.yml), assume uv is allowed and suggest uv commands. If the user said "use uv", always prefer uv over pip/poetry. If poetry/pipenv/conda is present, ask before switching to uv (see Mode Decision).
requirements.txt only: If the repo has requirements.txt but no pyproject.toml, ask whether the user wants to convert to uv before converting or using uv pip.
IDE interpreter: After uv creates or syncs
```
.venv
```
, try to set the workspace Python interpreter by adding or updating
```
python.defaultInterpreterPath
```
in
```
.vscode/settings.json
```
(see IDE Setup above).

新建Python项目： 运行
```
uv init
```
（或
```
uv init <name>
```
），然后
```
uv add
```
添加初始依赖，再执行
```
uv sync
```
。建议使用
```
uv run
```
执行运行/测试命令。
添加依赖： 使用
```
uv add <package>
```
。开发/可选依赖使用
```
uv add --dev <package>
```
。
运行任务： 项目中使用
```
uv run <command>
```
；脚本使用
```
uv run script.py
```
；一次性工具使用
```
uvx <tool>
```
。
无需手动激活虚拟环境： 优先使用
```
uv run
```
，避免Agent和用户依赖
```
source .venv/bin/activate
```
命令。
锁文件： 提交
```
uv.lock
```
；将其视为确保环境一致性的必需文件。拉取代码或修改依赖后，运行
```
uv sync
```
。在CI中使用
```
uv sync --locked
```
，这样如果锁文件与
```
pyproject.toml
```
不同步，任务会失败。
检测uv使用场景： 如果
```
pyproject.toml
```
存在且无poetry/pipenv/conda（无poetry.lock、Pipfile、environment.yml），则假设允许使用uv并建议相关命令。如果用户明确要求"使用uv"，则始终优先选择uv而非pip/poetry。如果存在poetry/pipenv/conda，切换到uv前需先询问用户（见模式选择部分）。
仅使用requirements.txt的场景： 如果仓库有requirements.txt但无pyproject.toml，在转换或使用uv pip前需询问用户是否要转换为uv。
IDE解释器配置： 当uv创建或同步
```
.venv
```
后，尝试通过添加或更新
```
.vscode/settings.json
```
中的
```
python.defaultInterpreterPath
```
来设置工作区Python解释器（见上述IDE配置部分）。

Common Commands Reference

常用命令参考

Task	Command
New project	`uv init [name]`
Add dependency	`uv add <pkg>`
Add dev dependency	`uv add --dev <pkg>`
Remove dependency	`uv remove <pkg>`
Install from lock	`uv sync`
Update lockfile	`uv lock`
Run in project	`uv run <cmd>`
Run script	`uv run script.py`
Run CLI tool once	`uvx <pkg> [args]`
Install tool	`uv tool install <pkg>`
Create venv	`uv venv`
Pin Python	`uv python pin 3.11`
Install Python	`uv python install 3.11`

任务	命令
新项目创建	`uv init [name]`
添加依赖	`uv add <pkg>`
添加开发依赖	`uv add --dev <pkg>`
删除依赖	`uv remove <pkg>`
从锁文件安装依赖	`uv sync`
更新锁文件	`uv lock`
项目中运行命令	`uv run <cmd>`
运行脚本	`uv run script.py`
一次性运行CLI工具	`uvx <pkg> [args]`
安装CLI工具	`uv tool install <pkg>`
创建虚拟环境	`uv venv`
固定Python版本	`uv python pin 3.11`
安装指定Python版本	`uv python install 3.11`

Additional Resources

额外资源

Full CLI and options: references/cli-and-commands.md
Example flows: references/examples.md
Common issues and fixes: references/troubleshooting.md
Docker and CI: references/docker-and-ci.md
Workspaces (monorepos) and resolution: references/workspaces-and-resolution.md

完整CLI及选项：references/cli-and-commands.md
示例流程：references/examples.md
常见问题与修复：references/troubleshooting.md
Docker与CI：references/docker-and-ci.md
工作区（单体仓库）与依赖解析：references/workspaces-and-resolution.md