⚡

uv包管理器Skill uv-package-manager

uv包管理器是一个用Rust编写的高性能Python包管理工具，用于快速安装依赖、管理虚拟环境、优化开发工作流和集成CI/CD，适用于现代Python项目。关键词：Python包管理，依赖解析，虚拟环境，CI/CD，性能优化。

DevOps 0 次安装 0 次浏览 更新于 3/13/2026

name: uv-package-manager description: 掌握uv包管理器，用于快速Python依赖管理、虚拟环境和现代Python项目工作流。在设置Python项目、管理依赖或使用uv优化Python开发工作流时使用。 version: 0.1.0

UV 包管理器

使用uv的全面指南，uv是一个用Rust编写的极快Python包安装器和解析器，用于现代Python项目管理和依赖工作流。

何时使用此技能

  • 快速设置新的Python项目
  • 比pip更快地管理Python依赖
  • 创建和管理虚拟环境
  • 安装Python解释器
  • 高效解析依赖冲突
  • 从pip/pip-tools/poetry迁移
  • 加速CI/CD管道
  • 管理单仓库Python项目
  • 使用锁文件实现可重复构建
  • 优化带有Python依赖的Docker构建

核心概念

1. 什么是uv？

  • 超快包安装器：比pip快10-100倍
  • 用Rust编写：利用Rust的性能
  • 即插即用的pip替代品：兼容pip工作流
  • 虚拟环境管理器：创建和管理venv
  • Python安装器：下载和管理Python版本
  • 解析器：高级依赖解析
  • 锁文件支持：可重复安装

2. 关键特性

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

3. UV与传统工具对比

  • vs pip：快10-100倍，更好的解析器
  • vs pip-tools：更快、更简单、更好的用户体验
  • vs poetry：更快、更少意见、更轻量
  • vs conda：更快、专注于Python

安装

快速安装

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 使用pip（如果已有Python）
pip install uv

# 使用Homebrew (macOS)
brew install uv

# 使用cargo（如果有Rust）
cargo install --git https://github.com/astral-sh/uv uv

验证安装

uv --version
# uv 0.x.x

快速开始

创建新项目

# 使用虚拟环境创建新项目
uv init my-project
cd my-project

# 或在当前目录创建
uv init .

# 初始化创建：
# - .python-version（Python版本）
# - pyproject.toml（项目配置）
# - README.md
# - .gitignore

安装依赖

# 安装包（如需则创建venv）
uv add requests pandas

# 安装开发依赖
uv add --dev pytest black ruff

# 从requirements.txt安装
uv pip install -r requirements.txt

# 从pyproject.toml安装
uv sync

虚拟环境管理

模式1：创建虚拟环境

# 使用uv创建虚拟环境
uv venv

# 使用特定Python版本创建
uv venv --python 3.12

# 使用自定义名称创建
uv venv my-env

# 使用系统站点包创建
uv venv --system-site-packages

# 指定位置
uv venv /path/to/venv

模式2：激活虚拟环境

# Linux/macOS
source .venv/bin/activate

# Windows（命令提示符）
.venv\Scripts\activate.bat

# Windows（PowerShell）
.venv\Scripts\Activate.ps1

# 或使用uv run（无需激活）
uv run python script.py
uv run pytest

模式3：使用uv run

# 运行Python脚本（自动激活venv）
uv run python app.py

# 运行已安装的CLI工具
uv run black .
uv run pytest

# 使用特定Python版本运行
uv run --python 3.11 python script.py

# 传递参数
uv run python script.py --arg value

包管理

模式4：添加依赖

# 添加包（添加到pyproject.toml）
uv add requests

# 添加带版本约束的包
uv add "django>=4.0,<5.0"

# 添加多个包
uv add numpy pandas matplotlib

# 添加开发依赖
uv add --dev pytest pytest-cov

# 添加可选依赖组
uv add --optional docs sphinx

# 从git添加
uv add git+https://github.com/user/repo.git

# 从git添加特定引用
uv add git+https://github.com/user/repo.git@v1.0.0

# 从本地路径添加
uv add ./local-package

# 添加可编辑本地包
uv add -e ./local-package

模式5：移除依赖

# 移除包
uv remove requests

# 移除开发依赖
uv remove --dev pytest

# 移除多个包
uv remove numpy pandas matplotlib

模式6：升级依赖

# 升级特定包
uv add --upgrade requests

# 升级所有包
uv sync --upgrade

# 升级包到最新
uv add --upgrade requests

# 显示可升级内容
uv tree --outdated

模式7：锁定依赖

# 生成uv.lock文件
uv lock

# 更新锁文件
uv lock --upgrade

# 锁定但不安装
uv lock --no-install

# 锁定特定包
uv lock --upgrade-package requests

Python版本管理

模式8：安装Python版本

# 安装Python版本
uv python install 3.12

# 安装多个版本
uv python install 3.11 3.12 3.13

# 安装最新版本
uv python install

# 列出已安装版本
uv python list

# 查找可用版本
uv python list --all-versions

模式9：设置Python版本

# 为项目设置Python版本
uv python pin 3.12

# 这会创建/更新.python-version文件

# 使用特定Python版本运行命令
uv --python 3.11 run python script.py

# 使用特定版本创建venv
uv venv --python 3.12

项目配置

模式10：使用uv的pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "我的优秀项目"
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 = [
    # uv管理的额外开发依赖
]

[tool.uv.sources]
# 自定义包源
my-package = { git = "https://github.com/user/repo.git" }

模式11：使用uv与现有项目

# 从requirements.txt迁移
uv add -r requirements.txt

# 从poetry迁移
# 已有pyproject.toml，直接使用：
uv sync

# 导出到requirements.txt
uv pip freeze > requirements.txt

# 导出带哈希值
uv pip freeze --require-hashes > requirements.txt

高级工作流

模式12：单仓库支持

# 项目结构
# monorepo/
#   packages/
#     package-a/
#       pyproject.toml
#     package-b/
#       pyproject.toml
#   pyproject.toml（根）

# 根pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# 安装所有工作空间包
uv sync

# 添加工作空间依赖
uv add --path ./packages/package-a

模式13：CI/CD集成

# .github/workflows/test.yml
name: 测试

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

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

      - name: 设置Python
        run: uv python install 3.12

      - name: 安装依赖
        run: uv sync --all-extras --dev

      - name: 运行测试
        run: uv run pytest

      - name: 运行代码检查
        run: |
          uv run ruff check .
          uv run black --check .

模式14：Docker集成

# Dockerfile
FROM python:3.12-slim

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

# 设置工作目录
WORKDIR /app

# 复制依赖文件
COPY pyproject.toml uv.lock ./

# 安装依赖
RUN uv sync --frozen --no-dev

# 复制应用代码
COPY . .

# 运行应用
CMD ["uv", "run", "python", "app.py"]

优化的多阶段构建：

# 多阶段Dockerfile
FROM python:3.12-slim AS builder

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

WORKDIR /app

# 安装依赖到venv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable

# 运行时阶段
FROM python:3.12-slim

WORKDIR /app

# 从构建器复制venv
COPY --from=builder /app/.venv .venv
COPY . .

# 使用venv
ENV PATH="/app/.venv/bin:$PATH"

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

模式15：锁文件工作流

# 创建锁文件（uv.lock）
uv lock

# 从锁文件安装（精确版本）
uv sync --frozen

# 更新锁文件但不安装
uv lock --no-install

# 在锁中升级特定包
uv lock --upgrade-package requests

# 检查锁文件是否最新
uv lock --check

# 导出锁文件到requirements.txt
uv export --format requirements-txt > requirements.txt

# 导出带哈希值以提高安全性
uv export --format requirements-txt --hash > requirements.txt

性能优化

模式16：使用全局缓存

# UV自动使用全局缓存，位置：
# Linux: ~/.cache/uv
# macOS: ~/Library/Caches/uv
# Windows: %LOCALAPPDATA%\uv\cache

# 清除缓存
uv cache clean

# 检查缓存大小
uv cache dir

模式17：并行安装

# UV默认并行安装包

# 控制并行度
uv pip install --jobs 4 package1 package2

# 无并行（顺序）
uv pip install --jobs 1 package

模式18：离线模式

# 仅从缓存安装（无网络）
uv pip install --offline package

# 离线从锁文件同步
uv sync --frozen --offline

与其他工具比较

uv vs pip

# pip
python -m venv .venv
source .venv/bin/activate
pip install requests pandas numpy
# ~30秒

# uv
uv venv
uv add requests pandas numpy
# ~2秒（快10-15倍）

uv vs poetry

# poetry
poetry init
poetry add requests pandas
poetry install
# ~20秒

# uv
uv init
uv add requests pandas
uv sync
# ~3秒（快6-7倍）

uv vs pip-tools

# pip-tools
pip-compile requirements.in
pip-sync requirements.txt
# ~15秒

# uv
uv lock
uv sync --frozen
# ~2秒（快7-8倍）

常见工作流

模式19：启动新项目

# 完整工作流
uv init my-project
cd my-project

# 设置Python版本
uv python pin 3.12

# 添加依赖
uv add fastapi uvicorn pydantic

# 添加开发依赖
uv add --dev pytest black ruff mypy

# 创建结构
mkdir -p src/my_project tests

# 运行测试
uv run pytest

# 格式化代码
uv run black .
uv run ruff check .

模式20：维护现有项目

# 克隆仓库
git clone https://github.com/user/project.git
cd project

# 安装依赖（自动创建venv）
uv sync

# 安装开发依赖
uv sync --all-extras

# 更新依赖
uv lock --upgrade

# 运行应用
uv run python app.py

# 运行测试
uv run pytest

# 添加新依赖
uv add new-package

# 提交更新文件
git add pyproject.toml uv.lock
git commit -m "添加new-package依赖"

工具集成

模式21：预提交钩子

# .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]

模式22：VS Code集成

// .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
  }
}

故障排除

常见问题

# 问题：找不到uv
# 解决：添加到PATH或重新安装
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

# 问题：错误的Python版本
# 解决：明确固定版本
uv python pin 3.12
uv venv --python 3.12

# 问题：依赖冲突
# 解决：检查解析
uv lock --verbose

# 问题：缓存问题
# 解决：清除缓存
uv cache clean

# 问题：锁文件不同步
# 解决：重新生成
uv lock --upgrade

最佳实践

项目设置

  1. 始终使用锁文件以确保可重复性
  2. 固定Python版本使用.python-version
  3. 分离开发依赖与生产依赖
  4. 使用uv run而不是激活venv
  5. 提交uv.lock到版本控制
  6. 在CI中使用–frozen以确保一致构建
  7. 利用全局缓存提高速度
  8. 使用工作空间用于单仓库
  9. 导出requirements.txt以提高兼容性
  10. 保持uv更新以获取最新功能

性能提示

# 在CI中使用冻结安装
uv sync --frozen

# 尽可能使用离线模式
uv sync --offline

# 并行操作（自动）
# uv默认执行

# 跨环境重用缓存
# uv全局共享缓存

# 使用锁文件跳过解析
uv sync --frozen  # 跳过解析

迁移指南

从pip + requirements.txt迁移

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

# 之后
uv venv
uv pip install -r requirements.txt
# 或更好：
uv init
uv add -r requirements.txt

从Poetry迁移

# 之前
poetry install
poetry add requests

# 之后
uv sync
uv add requests

# 保留现有pyproject.toml
# uv读取[project]和[tool.poetry]部分

从pip-tools迁移

# 之前
pip-compile requirements.in
pip-sync requirements.txt

# 之后
uv lock
uv sync --frozen

命令参考

基本命令

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

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

# Python管理
uv python install VERSION   # 安装Python
uv python list              # 列出已安装Python
uv python pin VERSION       # 固定Python版本

# 包安装（兼容pip）
uv pip install PACKAGE      # 安装包
uv pip uninstall PACKAGE    # 卸载包
uv pip freeze               # 列出已安装
uv pip list                 # 列出包

# 实用工具
uv cache clean              # 清除缓存
uv cache dir                # 显示缓存位置
uv --version                # 显示版本

资源

最佳实践总结

  1. 对所有新项目使用uv - 从uv init开始
  2. 提交锁文件 - 确保可重复构建
  3. 固定Python版本 - 使用.python-version
  4. 使用uv run - 避免手动venv激活
  5. 利用缓存 - 让uv管理全局缓存
  6. 在CI中使用–frozen - 精确复制
  7. 保持uv更新 - 快速发展的项目
  8. 使用工作空间 - 用于单仓库项目
  9. 导出以提高兼容性 - 需要时生成requirements.txt
  10. 阅读文档 - uv功能丰富且不断发展