uv-package-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UV Package Manager Skill

UV包管理器使用指南

When to Activate

适用场景

Activate this skill when:

Creating new Python projects
Adding or removing dependencies
Running Python scripts or tools
Managing virtual environments
Setting up Python version management

在以下场景中使用本技能：

创建新的Python项目
添加或移除依赖项
运行Python脚本或工具
管理虚拟环境
配置Python版本管理

Why UV?

为什么选择UV？

10-100x faster than pip (Rust implementation)
Unified tool - replaces pip, pip-tools, poetry, pyenv, virtualenv
Reliable - lock files for reproducible builds
Modern - built for current Python workflows

比pip快10-100倍（基于Rust实现）
一体化工具 - 替代pip、pip-tools、poetry、pyenv、virtualenv
可靠性高 - 通过锁定文件实现可复现的构建
现代化 - 为当前Python工作流打造

Quick Commands

快速命令

bash

undefined

bash

undefined

Project Management

项目管理

uv init # Create new project uv init --package my-lib # Create installable package

uv init # 创建新项目 uv init --package my-lib # 创建可安装的包

Dependencies

依赖项管理

uv add requests # Add dependency uv add --dev pytest # Add dev dependency uv remove package-name # Remove dependency

uv add requests # 添加依赖项 uv add --dev pytest # 添加开发依赖项 uv remove package-name # 移除依赖项

Running Code

运行代码

uv run script.py # Run Python script uv run pytest # Run installed tool uv run python -m module # Run module

uv run script.py # 运行Python脚本 uv run pytest # 运行已安装的工具 uv run python -m module # 运行模块

Environment

环境管理

uv sync # Sync dependencies uv sync --frozen # Sync without updating lock uv lock # Update lock file uv python install 3.12 # Install Python version

undefined

uv sync # 同步依赖项 uv sync --frozen # 同步时不更新锁定文件 uv lock # 更新锁定文件 uv python install 3.12 # 安装Python版本

undefined

Creating Projects

创建项目

bash

undefined

bash

undefined

Standard project

标准项目

uv init my-project cd my-project

Package project (for libraries)

包项目（用于库开发）

uv init --package my-library

Specify Python version

指定Python版本

uv init --python 3.11

undefined

uv init --python 3.11

undefined

Created Structure

生成的项目结构

my-project/
├── .python-version    # Python version
├── pyproject.toml     # Project config
├── .venv/             # Virtual environment (auto-created)
└── hello.py           # Sample script

my-project/
├── .python-version    # Python版本文件
├── pyproject.toml     # 项目配置文件
├── .venv/             # 虚拟环境（自动创建）
└── hello.py           # 示例脚本

Adding Dependencies

添加依赖项

bash

undefined

bash

undefined

Basic add

基础添加

uv add requests fastapi uvicorn

With version constraints

带版本约束

uv add "django>=4.2,<5.0" uv add "requests==2.31.0" uv add "fastapi[all]"

Dev dependencies

开发依赖项

uv add --dev pytest black ruff mypy

From git

从Git添加

uv add --git https://github.com/user/repo --branch develop

undefined

uv add --git https://github.com/user/repo --branch develop

undefined

Running Scripts

运行脚本

bash

undefined

bash

undefined

Run Python script

运行Python脚本

uv run script.py

Run with arguments

带参数运行

uv run script.py --input data.csv

Run dev tools

运行开发工具

uv run pytest tests/ -v uv run black . uv run ruff check .

Run with temporary dependency

带临时依赖项运行

uv run --with httpx fetch_data.py

Start Python REPL

启动Python交互式解释器

uv run python

undefined

uv run python

undefined

Virtual Environment

虚拟环境

UV automatically manages virtual environments:

bash

undefined

UV会自动管理虚拟环境：

bash

undefined

Created automatically on first use

首次使用时自动创建

uv sync # First sync uv add package # First package add uv run script.py # First run

uv sync # 首次同步 uv add package # 首次添加包 uv run script.py # 首次运行

Manual creation

手动创建

uv venv uv venv --python 3.11

Manual activation (rarely needed)

手动激活（很少需要）

source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows

undefined

source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows

undefined

Lock Files

锁定文件

bash

undefined

bash

undefined

Generate/update lock file

生成/更新锁定文件

uv lock

Sync from lock (normal)

从锁定文件同步（常规方式）

uv sync

Sync without updating (CI/CD)

同步时不更新锁定文件（CI/CD场景）

uv sync --frozen

Update specific package

更新指定包

uv lock --upgrade-package requests

ALWAYS commit these files:

请务必提交以下文件：

- pyproject.toml

- uv.lock

- .python-version

undefined

undefined

Python Version Management

Python版本管理

bash

undefined

bash

undefined

List available versions

列出可用版本

uv python list

Install specific version

安装指定版本

uv python install 3.12

Set project version

设置项目Python版本

echo "3.12" > .python-version

undefined

echo "3.12" > .python-version

undefined

Migration from pip

从pip迁移

bash

undefined

bash

undefined

Import requirements.txt

导入requirements.txt

uv init my-project cd my-project uv add -r requirements.txt

Import dev requirements

导入开发依赖项

uv add --dev -r requirements-dev.txt

undefined

uv add --dev -r requirements-dev.txt

undefined

Common pyproject.toml

常见pyproject.toml配置

toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.20.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
]

toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.20.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
]

Best Practices

最佳实践

DO ✅

DON'T ❌

不推荐做法 ❌

Commit
```
.venv/
```
directory
Use
```
*
```
for version constraints
Mix pip and uv in same project
Skip lock file updates after changes

提交
```
.venv/
```
目录
对版本约束使用
```
*
```
通配符
在同一项目中混合使用pip和uv
修改依赖项后跳过锁定文件更新

Troubleshooting

故障排除

bash

undefined

bash

undefined

Clear cache

清理缓存

uv cache clean

Verbose mode for debugging

启用详细模式调试

uv --verbose add package

Regenerate lock

重新生成锁定文件

uv lock uv sync

undefined

uv lock uv sync

undefined