uv（Python 包和项目管理器）的基本命令及镜像设置

samonyu
2,482 阅读4分钟

特性

  • 🚀 一个工具可以替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等等。
  • ⚡️ 比 pip 快 10 到 100 倍。
  • 🐍 安装和管理 Python 版本。
  • 🛠️ 运行和安装 Python 应用程序。
  • ❇️ 运行脚本，支持内置依赖元数据。
  • 🗂️ 提供全面的项目管理，具有通用的锁定文件。
  • 🔩 包括 pip 兼容接口，以获得熟悉的 CLI 并提高性能。
  • 🏢 支持 Cargo 风格的工作区，适用于可扩展的项目。
  • 💾 空间高效，具有全局缓存以实现依赖项去重。
  • ⏬ 通过 curl 或 pip 无需 Rust 或 Python 即可安装。
  • 🖥️ 支持 macOS、Linux 和 Windows。

基本命令

初始化Python项目

跳转到项目文件夹，然后init。

cd work-dir
uv init

初始化后，项目文件夹的结构如下。uv会通过pyproject.toml管理依赖（不同于requirements.txt）、Python的版本，以及项目的基本信息。这个与Javascript的package.json有异曲同工之妙。

同时，uv提倡使用虚拟环境（.venv），从而避免不同项目的Python依赖管理混乱的情况。

.  
├── .venv  
│ ├── bin  
│ ├── lib  
│ └── pyvenv.cfg  
├── .python-version  
├── README.md  
├── hello.py  
├── pyproject.toml  
└── uv.lock

依赖管理

  • 添加一个依赖。
uv add dependency-you-need
  • 删除一个依赖。
uv remove dependency-you-don't-need
  • 更新环境，通常用于获取源码后添加依赖。类似于JS的npm install。
uv sync

运行

  • 运行hello.py
uv run hello.py
  • 运行命令
uv run -- command-you-want-to-run
  • 提供临时依赖项并运行一个命令
  1. 创建一个临时的venv
  2. 安装依赖
  3. 运行命令

举个例子🌰，运行jupyter。

uv run --with jupyter jupyter notebook
uv run --with 'jupyter,jupyterlab-language-pack-zh-CN' jupyter notebook

pyproject.toml的设置

模板1

比较省事的模板：

  1. 在PyPi镜像的选择上，使用了教育网的镜像。在添加依赖的时候，需要使用uv add命令。
  2. 在Pytorch的下载上，使用Pytorch的官方源。
[project]  
name = "hello-world"  
version = "0.1.0"  
description = "Add your description here"  
readme = "README.md"  
dependencies = []

# Pytorch 设置：要求torch和torchvision采用pytorch-cu124索引（macos除外）

[tool.uv.sources]  
torch = [  
{ index = "pytorch-cu124", marker = "platform_system != 'Darwin'"},  
]  
torchvision = [  
{ index = "pytorch-cu124", marker = "platform_system != 'Darwin'"},  
]  
torchaudio = [  
{ index = "pytorch-cu124", marker = "platform_system != 'Darwin'"},  
]

[[tool.uv.index]]  
name = "pytorch-cu124"  
url = "https://download.pytorch.org/whl/cu124"

# 只允许torch从该索引安装，其他走PyPI
explicit = true

# 镜像设置
[tool.uv]
index-url = "https://mirrors.cernet.edu.cn/pypi/web/simple"

模板2（新!）

下面的设置模板考虑了以下两点：

  1. 在PyPi镜像的选择上，使用了教育网的镜像。在添加依赖的时候，需要使用uv add命令。
  2. 在Pytorch的下载上，根据CPU以及GPU的情况分别设置了针对这两种的下载设置。在添加Pytorch的时候，需要使用uv sync --extra cu130命令（注意后面的--extra cu130参数）
# 项目基本信息配置
[project]
# 项目名称
name = "gym-tutorial"
# 项目版本
version = "0.1.0"
# 项目描述
description = "Add your description here"
# 项目README文件
readme = "README.md"
# Python版本要求
requires-python = ">=3.14.0"
# 核心依赖包列表
dependencies = [
    "torch>=2.10.0",          # PyTorch深度学习框架
    "torchvision>=0.25.0",    # PyTorch计算机视觉库
]

# 可选依赖配置：根据CPU和GPU进行选择
[project.optional-dependencies]
# CPU版本的依赖
cpu = [
  "torch",      # CPU版本的PyTorch
  "torchvision",# CPU版本的torchvision
]
# CUDA 13.0版本的依赖（GPU加速）
cu130 = [
  "torch",      # GPU版本的PyTorch
  "torchvision",# GPU版本的torchvision
]

# UV工具配置
[tool.uv]
# PyPI镜像源设置
index-url = "https://mirrors.cernet.edu.cn/pypi/web/simple"
# 依赖冲突设置：CPU和CU130版本不能同时安装
conflicts = [
  [
    { extra = "cpu" },      # CPU版本
    { extra = "cu130" },    # GPU版本
  ],
]

# 包源配置：根据不同的extra选择不同的源
[tool.uv.sources]
# torch包的源配置
torch = [
  { index = "pytorch-cpu", extra = "cpu" },    # CPU版本使用pytorch-cpu索引
  { index = "pytorch-cu130", extra = "cu130" },# GPU版本使用pytorch-cu130索引
]
# torchvision包的源配置
torchvision = [
  { index = "pytorch-cpu", extra = "cpu" },    # CPU版本使用pytorch-cpu索引
  { index = "pytorch-cu130", extra = "cu130" },# GPU版本使用pytorch-cu130索引
]

# PyPI索引配置
# CPU版本的PyTorch索引
[[tool.uv.index]]
name = "pytorch-cpu"                # 索引名称
url = "https://download.pytorch.org/whl/cpu"  # CPU版本PyTorch的下载地址
explicit = true                     # 显式索引

# CUDA 13.0版本的PyTorch索引
[[tool.uv.index]]
name = "pytorch-cu130"              # 索引名称
url = "https://download.pytorch.org/whl/cu130"  # GPU版本PyTorch的下载地址
explicit = true                     # 显式索引

# 安装命令说明
# 安装CPU版本：uv sync --extra cpu
# 安装GPU版本：uv sync --extra cu130
# 切换版本时，先卸载当前版本，再安装目标版本
avatar
文章
阅读
粉丝