构建高效 Python 项目：基于 uv 的依赖管理全流程操作指南

汀丶人工智能

发布于 2025-05-21 12:16:46

35100

代码可运行

文章被收录于专栏：NLP/KGNLP/KG

运行总次数：0

代码可运行

1.核心

–

pyproject.toml

pyproject.toml 是 Python 项目的核心配置文件，用于定义项目元数据和依赖关系。

基本结构

[project]
name = "项目名称"
version = "版本号"
description = "项目描述"
requires-python = ">=3.12"  # Python 版本要求
dependencies = [
    "package1>=1.0.0",
    "package2>=2.0.0"
]

[project.optional-dependencies]
# 可选依赖组
group1 = [
    "package3>=3.0.0"
]

可选依赖

[project.optional-dependencies]
# Windows 特定依赖组
windows = [
    "pywin32>=306; platform_system == 'Windows'",  # Windows 系统 API
    "wmi>=1.5.1; platform_system == 'Windows'"     # Windows 管理接口
]

# macOS 特定依赖组
macos = [
    "pyobjc>=9.2; platform_system == 'Darwin'",    # macOS 系统 API
    "pyobjc-framework-Cocoa>=9.2; platform_system == 'Darwin'"
]

# Linux 特定依赖组
linux = [
    "python-xlib>=0.33; platform_system == 'Linux'",  # X11 接口
    "dbus-python>=1.3.2; platform_system == 'Linux'"  # D-Bus 接口
]


# 也可以合并一起
# 每个包是否安装，取决于其环境标记 platform_system 是否在当前平台满足。
merge=[
    "pywin32>=306; platform_system == 'Windows'",  # Windows 系统 API
    "wmi>=1.5.1; platform_system == 'Windows'"     # Windows 管理接口
    "pyobjc>=9.2; platform_system == 'Darwin'",    # macOS 系统 API
    "pyobjc-framework-Cocoa>=9.2; platform_system == 'Darwin'"
    "python-xlib>=0.33; platform_system == 'Linux'",  # X11 接口
    "dbus-python>=1.3.2; platform_system == 'Linux'"  # D-Bus 接口
]

uv.lock

uv.lock 是依赖锁定文件，用于确保在不同环境中安装完全相同的依赖版本。

主要功能

锁定所有依赖的具体版本
记录完整的依赖树
确保环境一致性
支持跨平台依赖管理

操作示例

# 安装主依赖+可选依赖
uv pip install -e ".[base]"

# 安装多个可选依赖
uv pip install -e ".[bas,windows]"

# 生成平台特定的 lock 文件
uv pip compile pyproject.toml -o uv.windows.lock

# 同步依赖
uv pip sync uv.windows.lock

2.依赖更新流程

# 1. 更新 pyproject.toml 中的依赖版本
# 2. 重新生成 lock 文件
uv pip compile pyproject.toml -o uv.lock

# 3. 同步依赖
uv pip sync uv.lock

3.多平台开发流程

为每个平台维护单独的 lock 文件：

uv.windows.lock
uv.mac.lock
uv.linux.lock

在切换平台时使用对应的 lock 文件：

# Windows 环境
uv pip sync uv.windows.lock

# macOS 环境
uv pip sync uv.mac.lock

# Linux 环境
uv pip sync uv.linux.lock

定期同步所有平台的 lock 文件：

 # 更新所有平台的 lock 文件
uv pip compile pyproject.toml --index-url https://download.pytorch.org/whl/cu128 -o uv.windows.lock
uv pip compile pyproject.toml --index-url https://download.pytorch.org/whl/cu128 -o uv.linux.lock
uv pip compile pyproject.toml -o uv.mac.lock

4.CI/CD 集成

在 CI/CD 流程中，建议使用以下步骤：

steps:
  - name: 安装依赖
    run: |
      # 根据平台选择正确的 lock 文件
      if [ "$RUNNER_OS" == "Windows" ]; then
        uv pip sync uv.windows.lock
      elif [ "$RUNNER_OS" == "macOS" ]; then
        uv pip sync uv.mac.lock
      else
        uv pip sync uv.linux.lock
      fi
      
      # 安装项目依赖
      uv pip install -e ".[base]"
      
      # 安装平台特定依赖
      if [ "$RUNNER_OS" == "Windows" ]; then
        uv pip install -e ".[windows]"
      elif [ "$RUNNER_OS" == "macOS" ]; then
        uv pip install -e ".[macos]"
      else
        uv pip install -e ".[linux]"
      fi

5.示例：使用 uv 管理 PyTorch依赖

PyTorch 的安装需要注意，因为不同平台包含 CPU 和 CUDA 两种版本。

在 pyproject.toml 中定义基础依赖

可以设计如下pyproject.toml文件：

[project]
name = "my-awesome-project"
dynamic = ["version"]
description = "项目描述"
requires-python = ">=3.12"  # Python 版本要求
# 主依赖选项
dependencies = [
    "numpy>=1.24.0",
		"pandas>=2.0.0"
]

[project.optional-dependencies]
# 单独设计一个torch依赖组
torch =[
    "torch>=2.6.0",
    "torchvision>=0.18.0",
    "torchaudio>=2.6.0",
]

基于 pyproject.toml 安装基础依赖（适合开发环境）

# 安装主依赖 + torch
uv pip install -e ".[torch]" \
 -i https://download.pytorch.org/whl/cu128
 --extra-index-url https://pypi.org/simple

生成平台特定的 lock 文件并安装依赖（适合部署环境）

# 生成 Windows GPU 版本的 lock 文件
uv pip compile pyproject.toml \
  --extra torch \
  --extra another_extra_dependency \ #如果有
    --index-url https://download.pytorch.org/whl/cu128 \
    --extra-index-url https://pypi.org/simple \
    -o uv.windows.lock
    
# Windows GPU 环境
uv pip sync uv.windows.lock

索引 URL 优先级说明：