UV Package Manager

UV 包管理器

Comprehensive guide to using uv, an extremely fast Python package installer and resolver written in Rust, for modern Python project management and dependency workflows.

本指南全面介绍如何使用uv——一款用Rust编写的超快速Python包安装器和解析器——进行现代化Python项目管理和依赖工作流。

When to Use This Skill

何时使用uv

Setting up new Python projects quickly
Managing Python dependencies faster than pip
Creating and managing virtual environments
Installing Python interpreters
Resolving dependency conflicts efficiently
Migrating from pip/pip-tools/poetry
Speeding up CI/CD pipelines
Managing monorepo Python projects
Working with lockfiles for reproducible builds
Optimizing Docker builds with Python dependencies

快速搭建新的Python项目
比pip更快地管理Python依赖
创建和管理虚拟环境
安装Python解释器
高效解决依赖冲突
从pip/pip-tools/poetry迁移
加速CI/CD流水线
管理单仓库（monorepo）Python项目
使用锁文件实现可复现的构建
优化包含Python依赖的Docker构建

Core Concepts

核心概念

1. What is uv?

1. 什么是uv？

Ultra-fast package installer: 10-100x faster than pip
Written in Rust: Leverages Rust's performance
Drop-in pip replacement: Compatible with pip workflows
Virtual environment manager: Create and manage venvs
Python installer: Download and manage Python versions
Resolver: Advanced dependency resolution
Lockfile support: Reproducible installations

超快速包安装器：比pip快10-100倍
基于Rust编写：借助Rust的高性能
pip的直接替代品：兼容pip工作流
虚拟环境管理器：创建和管理虚拟环境
Python安装器：下载和管理Python版本
依赖解析器：高级依赖解析功能
支持锁文件：可复现的安装过程

2. Key Features

2. 核心特性

Blazing fast installation speeds
Disk space efficient with global cache
Compatible with pip, pip-tools, poetry
Comprehensive dependency resolution
Cross-platform support (Linux, macOS, Windows)
No Python required for installation
Built-in virtual environment support

极快的安装速度
全局缓存节省磁盘空间
兼容pip、pip-tools、poetry
全面的依赖解析
跨平台支持（Linux、macOS、Windows）
安装无需Python环境
内置虚拟环境支持

3. UV vs Traditional Tools

3. uv与传统工具对比

vs pip: 10-100x faster, better resolver
vs pip-tools: Faster, simpler, better UX
vs poetry: Faster, less opinionated, lighter
vs conda: Faster, Python-focused

vs pip：快10-100倍，解析器更优秀
vs pip-tools：更快、更简单、用户体验更好
vs poetry：更快、约束更少、更轻量化
vs conda：更快、专注于Python生态

Installation

安装

Quick Install

快速安装

bash

undefined

bash

undefined

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Using pip (if you already have Python)

pip install uv

Using Homebrew (macOS)

brew install uv

Using cargo (if you have Rust)

cargo install --git https://github.com/astral-sh/uv uv

undefined

cargo install --git https://github.com/astral-sh/uv uv

undefined

Verify Installation

验证安装

bash

uv --version

bash

uv --version

uv 0.x.x

undefined

undefined

Quick Start

快速开始

Create a New Project

创建新项目

bash

undefined

bash

undefined

Create new project with virtual environment

创建带虚拟环境的新项目

uv init my-project cd my-project

Or create in current directory

或在当前目录创建

uv init .

Initialize creates:

初始化会生成：

- .python-version (Python version)

- .python-version（Python版本文件）

- pyproject.toml (project config)

- pyproject.toml（项目配置文件）

- README.md

- .gitignore

undefined

undefined

Install Dependencies

安装依赖

bash

undefined

bash

undefined

Install packages (creates venv if needed)

安装包（需要时自动创建虚拟环境）

uv add requests pandas

Install dev dependencies

安装开发依赖

uv add --dev pytest black ruff

Install from requirements.txt

从requirements.txt安装

uv pip install -r requirements.txt

Install from pyproject.toml

从pyproject.toml安装

uv sync

undefined

uv sync

undefined

Virtual Environment Management

虚拟环境管理

Pattern 1: Creating Virtual Environments

模式1：创建虚拟环境

bash

undefined

bash

undefined

Create virtual environment with uv

使用uv创建虚拟环境

uv venv

Create with specific Python version

创建指定Python版本的虚拟环境

uv venv --python 3.12

Create with custom name

创建自定义名称的虚拟环境

uv venv my-env

Create with system site packages

创建包含系统站点包的虚拟环境

uv venv --system-site-packages

Specify location

指定虚拟环境位置

uv venv /path/to/venv

undefined

uv venv /path/to/venv

undefined

Pattern 2: Activating Virtual Environments

模式2：激活虚拟环境

bash

undefined

bash

undefined

Linux/macOS

source .venv/bin/activate

Windows (Command Prompt)

Windows（命令提示符）

.venv\Scripts\activate.bat

Windows (PowerShell)

Windows（PowerShell）

.venv\Scripts\Activate.ps1

Or use uv run (no activation needed)

或使用uv run（无需激活）

uv run python script.py uv run pytest

undefined

uv run python script.py uv run pytest

undefined

Pattern 3: Using uv run

模式3：使用uv run

bash

undefined

bash

undefined

Run Python script (auto-activates venv)

运行Python脚本（自动激活虚拟环境）

uv run python app.py

Run installed CLI tool

运行已安装的CLI工具

uv run black . uv run pytest

Run with specific Python version

使用指定Python版本运行

uv run --python 3.11 python script.py

Pass arguments

传递参数

uv run python script.py --arg value

undefined

uv run python script.py --arg value

undefined

Package Management

包管理

Pattern 4: Adding Dependencies

模式4：添加依赖

bash

undefined

bash

undefined

Add package (adds to pyproject.toml)

添加包（会写入pyproject.toml）

uv add requests

Add with version constraint

添加带版本约束的包

uv add "django>=4.0,<5.0"

Add multiple packages

添加多个包

uv add numpy pandas matplotlib

Add dev dependency

添加开发依赖

uv add --dev pytest pytest-cov

Add optional dependency group

添加可选依赖组

uv add --optional docs sphinx

Add from git

从Git仓库添加

uv add git+https://github.com/user/repo.git

Add from git with specific ref

从Git仓库指定版本添加

uv add git+https://github.com/user/repo.git@v1.0.0

Add from local path

从本地路径添加

uv add ./local-package

Add editable local package

添加可编辑的本地包

uv add -e ./local-package

undefined

uv add -e ./local-package

undefined

Pattern 5: Removing Dependencies

模式5：移除依赖

bash

undefined

bash

undefined

Remove package

移除包

uv remove requests

Remove dev dependency

移除开发依赖

uv remove --dev pytest

Remove multiple packages

移除多个包

uv remove numpy pandas matplotlib

undefined

uv remove numpy pandas matplotlib

undefined

Pattern 6: Upgrading Dependencies

模式6：升级依赖

bash

undefined

bash

undefined

Upgrade specific package

升级指定包

uv add --upgrade requests

Upgrade all packages

升级所有包

uv sync --upgrade

Upgrade package to latest

将包升级到最新版本

uv add --upgrade requests

Show what would be upgraded

查看可升级的包

uv tree --outdated

undefined

uv tree --outdated

undefined

Pattern 7: Locking Dependencies

模式7：锁定依赖

bash

undefined

bash

undefined

Generate uv.lock file

生成uv.lock文件

uv lock

Update lock file

更新锁文件

uv lock --upgrade

Lock without installing

仅生成锁文件不安装

uv lock --no-install

Lock specific package

锁定指定包

uv lock --upgrade-package requests

undefined

uv lock --upgrade-package requests

undefined

Python Version Management

Python版本管理

Pattern 8: Installing Python Versions

模式8：安装Python版本

bash

undefined

bash

undefined

Install Python version

安装指定Python版本

uv python install 3.12

Install multiple versions

安装多个Python版本

uv python install 3.11 3.12 3.13

Install latest version

安装最新Python版本

uv python install

List installed versions

列出已安装的版本

uv python list

Find available versions

查看可用版本

uv python list --all-versions

undefined

uv python list --all-versions

undefined

Pattern 9: Setting Python Version

模式9：设置Python版本

bash

undefined

bash

undefined

Set Python version for project

为项目设置Python版本

uv python pin 3.12

This creates/updates .python-version file

该命令会创建/更新.python-version文件

Use specific Python version for command

使用指定Python版本执行命令

uv --python 3.11 run python script.py

Create venv with specific version

创建指定Python版本的虚拟环境

uv venv --python 3.12

undefined

uv venv --python 3.12

undefined

Project Configuration

项目配置

Pattern 10: pyproject.toml with uv

模式10：使用uv的pyproject.toml配置

toml

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]
docs = [
    "sphinx>=7.0.0",
    "sphinx-rtd-theme>=1.3.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    # Additional dev dependencies managed by uv
]

[tool.uv.sources]

toml

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
    "click>=8.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]
docs = [
    "sphinx>=7.0.0",
    "sphinx-rtd-theme>=1.3.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    # Additional dev dependencies managed by uv
]

[tool.uv.sources]

Custom package sources

my-package = { git = "https://github.com/user/repo.git" }

undefined

my-package = { git = "https://github.com/user/repo.git" }

undefined

Pattern 11: Using uv with Existing Projects

模式11：在现有项目中使用uv

bash

undefined

bash

undefined

Migrate from requirements.txt

从requirements.txt迁移

uv add -r requirements.txt

Migrate from poetry

从poetry迁移

Already have pyproject.toml, just use:

已有pyproject.toml，直接执行：

uv sync

Export to requirements.txt

导出到requirements.txt

uv pip freeze > requirements.txt

Export with hashes

导出带哈希值的版本

uv pip freeze --require-hashes > requirements.txt

undefined

uv pip freeze --require-hashes > requirements.txt

undefined

Advanced Workflows

高级工作流

Pattern 12: Monorepo Support

模式12：单仓库（Monorepo）支持

bash

undefined

bash

undefined

Project structure

项目结构

monorepo/

packages/

package-a/

pyproject.toml

package-b/

pyproject.toml

pyproject.toml (root)

pyproject.toml（根目录）

Root pyproject.toml

根目录pyproject.toml配置

[tool.uv.workspace] members = ["packages/*"]

Install all workspace packages

安装所有工作区包

uv sync

Add workspace dependency

添加工作区依赖

uv add --path ./packages/package-a

undefined

uv add --path ./packages/package-a

undefined

Pattern 13: CI/CD Integration

模式13：CI/CD集成

yaml

undefined

yaml

undefined

.github/workflows/test.yml

name: Tests

on: [push, pull_request]

jobs: test: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - name: Install uv
    uses: astral-sh/setup-uv@v2
    with:
      enable-cache: true

  - name: Set up Python
    run: uv python install 3.12

  - name: Install dependencies
    run: uv sync --all-extras --dev

  - name: Run tests
    run: uv run pytest

  - name: Run linting
    run: |
      uv run ruff check .
      uv run black --check .

undefined

name: Tests

on: [push, pull_request]

jobs: test: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - name: Install uv
    uses: astral-sh/setup-uv@v2
    with:
      enable-cache: true

  - name: Set up Python
    run: uv python install 3.12

  - name: Install dependencies
    run: uv sync --all-extras --dev

  - name: Run tests
    run: uv run pytest

  - name: Run linting
    run: |
      uv run ruff check .
      uv run black --check .

undefined

Pattern 14: Docker Integration

模式14：Docker集成

dockerfile

undefined

dockerfile

undefined

Dockerfile

FROM python:3.12-slim

Install uv

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

Set working directory

WORKDIR /app

Copy dependency files

COPY pyproject.toml uv.lock ./

Install dependencies

RUN uv sync --frozen --no-dev

Copy application code

COPY . .

Run application

CMD ["uv", "run", "python", "app.py"]


**Optimized multi-stage build:**

```dockerfile

CMD ["uv", "run", "python", "app.py"]


**优化的多阶段构建：**

```dockerfile

Multi-stage Dockerfile

FROM python:3.12-slim AS builder

Install uv

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app

Install dependencies to venv

COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev --no-editable

Runtime stage

FROM python:3.12-slim

WORKDIR /app

FROM python:3.12-slim

WORKDIR /app

Copy venv from builder

COPY --from=builder /app/.venv .venv COPY . .

Use venv

ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "app.py"]

undefined

ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "app.py"]

undefined

Pattern 15: Lockfile Workflows

模式15：锁文件工作流

bash

undefined

bash

undefined

Create lockfile (uv.lock)

创建锁文件（uv.lock）

uv lock

Install from lockfile (exact versions)

从锁文件安装（精确版本）

uv sync --frozen

Update lockfile without installing

更新锁文件但不安装

uv lock --no-install

Upgrade specific package in lock

升级锁文件中的指定包

uv lock --upgrade-package requests

Check if lockfile is up to date

检查锁文件是否最新

uv lock --check

Export lockfile to requirements.txt

将锁文件导出为requirements.txt

uv export --format requirements-txt > requirements.txt

Export with hashes for security

导出带哈希值的版本以提升安全性

uv export --format requirements-txt --hash > requirements.txt

undefined

uv export --format requirements-txt --hash > requirements.txt

undefined

Performance Optimization

性能优化

Pattern 16: Using Global Cache

模式16：使用全局缓存

bash

undefined

bash

undefined

UV automatically uses global cache at:

uv自动使用以下路径的全局缓存：

Linux: ~/.cache/uv

macOS: ~/Library/Caches/uv

Windows: %LOCALAPPDATA%\uv\cache

Clear cache

清理缓存

uv cache clean

Check cache size

查看缓存路径

uv cache dir

undefined

uv cache dir

undefined

Pattern 17: Parallel Installation

模式17：并行安装

bash

undefined

bash

undefined

UV installs packages in parallel by default

uv默认并行安装包

Control parallelism

控制并行数量

uv pip install --jobs 4 package1 package2

No parallel (sequential)

禁用并行（串行安装）

uv pip install --jobs 1 package

undefined

uv pip install --jobs 1 package

undefined

Pattern 18: Offline Mode

模式18：离线模式

bash

undefined

bash

undefined

Install from cache only (no network)

仅从缓存安装（无需网络）

uv pip install --offline package

Sync from lockfile offline

离线模式下从锁文件同步

uv sync --frozen --offline

undefined

uv sync --frozen --offline

undefined

Comparison with Other Tools

与其他工具对比

uv vs pip

bash

undefined

bash

undefined

pip

python -m venv .venv source .venv/bin/activate pip install requests pandas numpy

~30 seconds

uv

uv venv uv add requests pandas numpy

~2 seconds (10-15x faster)

undefined

undefined

uv vs poetry

bash

undefined

bash

undefined

poetry

poetry init poetry add requests pandas poetry install

~20 seconds

uv

uv init uv add requests pandas uv sync

~3 seconds (6-7x faster)

undefined

undefined

uv vs pip-tools

bash

undefined

bash

undefined

pip-tools

pip-compile requirements.in pip-sync requirements.txt

~15 seconds

uv

uv lock uv sync --frozen

~2 seconds (7-8x faster)

undefined

undefined

Common Workflows

常见工作流

Pattern 19: Starting a New Project

模式19：启动新项目

bash

undefined

bash

undefined

Complete workflow

完整工作流

uv init my-project cd my-project

Set Python version

设置Python版本

uv python pin 3.12

Add dependencies

添加依赖

uv add fastapi uvicorn pydantic

Add dev dependencies

添加开发依赖

uv add --dev pytest black ruff mypy

Create structure

创建项目结构

mkdir -p src/my_project tests

Run tests

运行测试

uv run pytest

Format code

格式化代码

uv run black . uv run ruff check .

undefined

uv run black . uv run ruff check .

undefined

Pattern 20: Maintaining Existing Project

模式20：维护现有项目

bash

undefined

bash

undefined

Clone repository

克隆仓库

git clone https://github.com/user/project.git cd project

Install dependencies (creates venv automatically)

安装依赖（自动创建虚拟环境）

uv sync

Install with dev dependencies

安装包含开发依赖的所有包

uv sync --all-extras

Update dependencies

更新依赖

uv lock --upgrade

Run application

运行应用

uv run python app.py

Run tests

运行测试

uv run pytest

Add new dependency

添加新依赖

uv add new-package

Commit updated files

提交更新的文件

git add pyproject.toml uv.lock git commit -m "Add new-package dependency"

undefined

git add pyproject.toml uv.lock git commit -m "Add new-package dependency"

undefined

Tool Integration

工具集成

Pattern 21: Pre-commit Hooks

模式21：预提交钩子

yaml

undefined

yaml

undefined

.pre-commit-config.yaml

repos:

repo: local hooks:
- id: uv-lock name: uv lock entry: uv lock language: system pass_filenames: false
- id: ruff name: ruff entry: uv run ruff check --fix language: system types: [python]
- id: black name: black entry: uv run black language: system types: [python]

undefined

repos:

repo: local hooks:
- id: uv-lock name: uv lock entry: uv lock language: system pass_filenames: false
- id: ruff name: ruff entry: uv run ruff check --fix language: system types: [python]
- id: black name: black entry: uv run black language: system types: [python]

undefined

Pattern 22: VS Code Integration

模式22：VS Code集成

json

// .vscode/settings.json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["-v"],
  "python.linting.enabled": true,
  "python.formatting.provider": "black",
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  }
}

json

// .vscode/settings.json
{
  \"python.defaultInterpreterPath\": \"${workspaceFolder}/.venv/bin/python\",
  \"python.terminal.activateEnvironment\": true,
  \"python.testing.pytestEnabled\": true,
  \"python.testing.pytestArgs\": [\"-v\"],
  \"python.linting.enabled\": true,
  \"python.formatting.provider\": \"black\",
  \"[python]\": {
    \"editor.defaultFormatter\": \"ms-python.black-formatter\",
    \"editor.formatOnSave\": true
  }
}

Troubleshooting

故障排除

Common Issues

常见问题

bash

undefined

bash

undefined

Issue: uv not found

问题：找不到uv命令

Solution: Add to PATH or reinstall

解决方案：添加到PATH或重新安装

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

Issue: Wrong Python version

问题：Python版本错误

Solution: Pin version explicitly

解决方案：显式固定版本

uv python pin 3.12 uv venv --python 3.12

Issue: Dependency conflict

问题：依赖冲突

Solution: Check resolution

解决方案：查看解析过程

uv lock --verbose

Issue: Cache issues

问题：缓存问题

Solution: Clear cache

解决方案：清理缓存

uv cache clean

Issue: Lockfile out of sync

问题：锁文件与配置不同步

Solution: Regenerate

解决方案：重新生成锁文件

uv lock --upgrade

undefined

uv lock --upgrade

undefined

Best Practices

最佳实践

Project Setup

项目搭建

Always use lockfiles for reproducibility
Pin Python version with .python-version
Separate dev dependencies from production
Use uv run instead of activating venv
Commit uv.lock to version control
Use --frozen in CI for consistent builds
Leverage global cache for speed
Use workspace for monorepos
Export requirements.txt for compatibility
Keep uv updated for latest features

始终使用锁文件以确保可复现性
固定Python版本使用.python-version文件
分离开发依赖与生产依赖
使用uv run替代手动激活虚拟环境
将uv.lock提交到版本控制
在CI中使用--frozen参数确保构建一致性
利用全局缓存提升速度
为单仓库项目使用工作区
导出兼容文件——需要时生成requirements.txt
保持uv更新获取最新功能

Performance Tips

性能技巧

bash

undefined

bash

undefined

Use frozen installs in CI

在CI中使用冻结安装

uv sync --frozen

Use offline mode when possible

尽可能使用离线模式

uv sync --offline

Parallel operations (automatic)

并行操作（默认开启）

uv does this by default

uv默认自动并行

Reuse cache across environments

在不同环境间复用缓存

uv shares cache globally

uv全局共享缓存

Use lockfiles to skip resolution

使用锁文件跳过解析步骤

uv sync --frozen # skips resolution

undefined

uv sync --frozen # 跳过解析

undefined

Migration Guide

迁移指南

From pip + requirements.txt

从pip + requirements.txt迁移

bash

undefined

bash

undefined

Before

之前的操作

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

After

迁移后操作

uv venv uv pip install -r requirements.txt

Or better:

更优方案：

uv init uv add -r requirements.txt

undefined

uv init uv add -r requirements.txt

undefined

From Poetry

从Poetry迁移

bash

undefined

bash

undefined

Before

之前的操作

poetry install poetry add requests

After

迁移后操作

uv sync uv add requests

Keep existing pyproject.toml

保留现有pyproject.toml

uv reads [project] and [tool.poetry] sections

uv会读取[project]和[tool.poetry]配置段

undefined

undefined

From pip-tools

从pip-tools迁移

bash

undefined

bash

undefined

Before

之前的操作

pip-compile requirements.in pip-sync requirements.txt

After

迁移后操作

uv lock uv sync --frozen

undefined

uv lock uv sync --frozen

undefined

Command Reference

命令参考

Essential Commands

核心命令

bash

undefined

bash

undefined

Project management

项目管理

uv init [PATH] # Initialize project uv add PACKAGE # Add dependency uv remove PACKAGE # Remove dependency uv sync # Install dependencies uv lock # Create/update lockfile

uv init [PATH] # 初始化项目 uv add PACKAGE # 添加依赖 uv remove PACKAGE # 移除依赖 uv sync # 安装依赖 uv lock # 创建/更新锁文件

Virtual environments

虚拟环境

uv venv [PATH] # Create venv uv run COMMAND # Run in venv

uv venv [PATH] # 创建虚拟环境 uv run COMMAND # 在虚拟环境中运行命令

Python management

Python版本管理

uv python install VERSION # Install Python uv python list # List installed Pythons uv python pin VERSION # Pin Python version

uv python install VERSION # 安装Python版本 uv python list # 列出已安装的Python版本 uv python pin VERSION # 固定项目Python版本

Package installation (pip-compatible)

包安装（兼容pip）

uv pip install PACKAGE # Install package uv pip uninstall PACKAGE # Uninstall package uv pip freeze # List installed uv pip list # List packages

uv pip install PACKAGE # 安装包 uv pip uninstall PACKAGE # 卸载包 uv pip freeze # 列出已安装包 uv pip list # 列出包信息

Utility

工具类命令

uv cache clean # Clear cache uv cache dir # Show cache location uv --version # Show version

undefined

uv cache clean # 清理缓存 uv cache dir # 查看缓存路径 uv --version # 查看uv版本

undefined

Resources

资源

Official documentation: https://docs.astral.sh/uv/
GitHub repository: https://github.com/astral-sh/uv
Astral blog: https://astral.sh/blog
Migration guides: https://docs.astral.sh/uv/guides/
Comparison with other tools: https://docs.astral.sh/uv/pip/compatibility/

官方文档：https://docs.astral.sh/uv/
GitHub仓库：https://github.com/astral-sh/uv
Astral博客：https://astral.sh/blog
迁移指南：https://docs.astral.sh/uv/guides/
与其他工具对比：https://docs.astral.sh/uv/pip/compatibility/

Best Practices Summary

最佳实践总结

Use uv for all new projects - Start with
```
uv init
```
Commit lockfiles - Ensure reproducible builds
Pin Python versions - Use .python-version
Use uv run - Avoid manual venv activation
Leverage caching - Let uv manage global cache
Use --frozen in CI - Exact reproduction
Keep uv updated - Fast-moving project
Use workspaces - For monorepo projects
Export for compatibility - Generate requirements.txt when needed
Read the docs - uv is feature-rich and evolving

所有新项目都使用uv——从
```
uv init
```
开始
提交锁文件——确保构建可复现
固定Python版本——使用.python-version文件
使用uv run——避免手动激活虚拟环境
利用全局缓存——提升速度
在CI中使用--frozen——确保构建一致
保持uv更新——项目迭代快速
使用工作区——管理单仓库项目
导出兼容文件——需要时生成requirements.txt
阅读官方文档——uv功能丰富且持续演进

uv-package-manager

Original

Translation

UV Package Manager

UV 包管理器

When to Use This Skill

何时使用uv

Core Concepts

核心概念

1. What is uv?

1. 什么是uv？

2. Key Features

2. 核心特性

3. UV vs Traditional Tools

3. uv与传统工具对比

Installation

安装

Quick Install

快速安装

macOS/Linux

macOS/Linux

Windows (PowerShell)

Windows (PowerShell)

Using pip (if you already have Python)

Using pip (if you already have Python)

Using Homebrew (macOS)

Using Homebrew (macOS)

Using cargo (if you have Rust)

Using cargo (if you have Rust)

Verify Installation

验证安装

uv 0.x.x

uv 0.x.x

Quick Start

快速开始

Create a New Project

创建新项目

Create new project with virtual environment

创建带虚拟环境的新项目

Or create in current directory

或在当前目录创建

Initialize creates:

初始化会生成：

- .python-version (Python version)

- .python-version（Python版本文件）

- pyproject.toml (project config)

- pyproject.toml（项目配置文件）

- README.md

- README.md

- .gitignore

- .gitignore

Install Dependencies

安装依赖

Install packages (creates venv if needed)

安装包（需要时自动创建虚拟环境）

Install dev dependencies

安装开发依赖

Install from requirements.txt

从requirements.txt安装

Install from pyproject.toml

从pyproject.toml安装

Virtual Environment Management

虚拟环境管理

Pattern 1: Creating Virtual Environments

模式1：创建虚拟环境

Create virtual environment with uv

使用uv创建虚拟环境

Create with specific Python version

创建指定Python版本的虚拟环境

Create with custom name

创建自定义名称的虚拟环境

Create with system site packages

创建包含系统站点包的虚拟环境

Specify location

指定虚拟环境位置

Pattern 2: Activating Virtual Environments

模式2：激活虚拟环境

Linux/macOS

Linux/macOS

Windows (Command Prompt)