Uv

uv 是 Astral 推出的 Python 包管理工具，目标是把常见 Python 开发工作流收敛到一个更快、更统一的命令行工具里。它可以管理项目依赖、虚拟环境、Python 版本，也可以像 pipx 一样运行或安装 Python 命令行工具。

安装

macOS 可以通过 Homebrew 安装：

brew install uv

也可以使用官方安装脚本：

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

安装后检查版本：

uv --version

创建项目

创建一个新项目：

uv init hello-uv
cd hello-uv

uv init 会生成基础项目结构和 pyproject.toml。之后可以直接添加依赖：

uv add requests

运行项目命令：

uv run python main.py

uv run 会根据项目配置准备环境，并在对应虚拟环境里执行命令。日常使用时，不需要手动反复激活和退出虚拟环境。

管理依赖

添加依赖：

uv add fastapi

添加开发依赖：

uv add --dev pytest ruff

删除依赖：

uv remove fastapi

同步依赖：

uv sync

uv 会维护锁文件，让不同机器上的依赖解析结果更稳定。团队项目里，锁文件可以帮助减少“我这里能跑”的环境差异。

管理 Python 版本

uv 可以发现系统里已有的 Python，也可以自己安装 Python 版本。

安装 Python：

uv python install 3.12

查看可用 Python：

uv python list

用指定 Python 创建环境或运行命令：

uv run --python 3.12 python --version

这让 uv 可以覆盖一部分 pyenv 的使用场景。对于只想快速拿到某个 Python 版本来跑项目的人来说，会更直接。

替代 pip

如果你已经有虚拟环境，也可以使用 uv pip 兼容常见 pip 工作流。

创建虚拟环境：

uv venv

安装包：

uv pip install flask

从 requirements.txt 安装：

uv pip install -r requirements.txt

这种方式适合迁移已有项目：先不改项目结构，只把慢的 pip install 换成 uv pip install。

配置 PyTorch

PyTorch 的包分发和普通 Python 包不太一样。很多 wheel 不只在 PyPI 上发布，还会按 CPU、CUDA、ROCm、Intel GPU 等后端放在 PyTorch 自己的 index 里。因此在 uv 项目里使用 PyTorch 时，最好明确配置 torch、torchvision 等包从哪个 index 安装。

如果项目只需要 CPU 版本，可以在 pyproject.toml 里添加：

[project]
dependencies = [
  "torch",
  "torchvision",
]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu" },
]
torchvision = [
  { index = "pytorch-cpu" },
]

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

这里的 explicit = true 很重要，它表示这个 index 只给显式指定的包使用。这样 jinja2、numpy 之类普通依赖仍然会从默认 PyPI 解析，避免整个项目都被 PyTorch index 影响。

如果希望 Linux 使用 CUDA 版本，macOS 和 Windows 使用 CPU 或 PyPI 默认包，可以用环境 marker 区分：

[project]
dependencies = [
  "torch",
  "torchvision",
]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu130", marker = "sys_platform == 'linux'" },
]
torchvision = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu130", marker = "sys_platform == 'linux'" },
]

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

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

需要注意，PyTorch 不提供 macOS 的 CUDA 构建，所以配置 CUDA index 时要用 sys_platform 限制到 Linux 或 Windows。否则在 macOS 上同步依赖时容易解析失败。

如果只是临时安装，也可以直接使用 uv pip 指定 index：

uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

这种方式适合一次性实验；如果是项目依赖，建议写进 pyproject.toml，让配置可以被版本控制和团队复用。

运行命令行工具

uvx 可以临时运行 Python 包提供的命令行工具，类似 pipx run。

例如临时运行 ruff：

uvx ruff check .

如果希望长期安装某个工具：

uv tool install ruff

之后可以直接运行：

ruff --version

这种方式适合安装 ruff、black、httpie、cookiecutter 这类 Python CLI 工具，避免把全局 Python 环境弄乱。

总结

uv 适合替代或整合多种 Python 工具：

• 替代 pip：更快安装依赖。
• 替代 virtualenv：创建和管理虚拟环境。
• 替代 pipx：运行和安装 Python CLI 工具。
• 部分替代 pyenv：安装和选择 Python 版本。
• 替代部分 poetry / pdm 工作流：管理项目依赖和锁文件。

如果是新项目，可以直接从 uv init 开始；如果是旧项目，可以先从 uv pip install -r requirements.txt 这种低风险方式迁移。