uv Python 环境安装指南

1. uv 简介

uv 是由 Astral 团队（Ruff 的作者）用 Rust 开发的 Python 包与项目管理器，旨在替代 pip、pip-tools、virtualenv 等工具。 它兼容 Python 的 pyproject.toml 标准，同时提供极快的依赖解析和安装速度。

主要特性：单一二进制文件、零依赖安装、10~100 倍于 pip 的安装速度、内置虚拟环境管理、Python 版本管理。

2. macOS — 通过 Homebrew 安装

macOS 用户推荐使用 Homebrew 安装 uv，安装和更新都非常方便。

前置条件：确保系统已安装 Homebrew（参考 https://brew.sh ）。

brew install uv

安装完成后，Homebrew 会将 uv 放在 /opt/homebrew/bin/uv（Apple Silicon）或 /usr/local/bin/uv（Intel）， 该路径通常在 $PATH 中，无需额外配置。

后续更新 uv 直接运行：

brew upgrade uv

3. Linux — 通过官方脚本安装

Linux 系统（Ubuntu / Debian / CentOS / Arch 等）推荐使用官方提供的安装脚本，一行命令即可完成安装。

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

脚本会自动下载最新版本的 uv 二进制文件，并安装到 ~/.local/bin/uv 目录下，同时自动追加 $PATH 配置到 ~/.bashrc 或 ~/.zshrc。

如果你的 ~/.local/bin 原本不在 $PATH 中，安装完成后需要手动 source 一下配置文件使其生效：

source ~/.bashrc    # bash 用户
# 或
source ~/.zshrc     # zsh 用户

后续更新 uv 可再次执行同一安装脚本，或使用 uv 自带的更新命令：

uv self update

4. 验证安装

无论 macOS 还是 Linux，安装完成后使用以下命令验证 uv 是否可用：

uv --version

正确输出示例：

uv 0.6.11 (Homebrew 2026-04-15)

5. Python 版本管理（可选）

uv 内置 Python 版本管理功能，无需手动安装 Python。可以列出可用版本并安装指定版本：

uv python list

安装指定 Python 版本（如 CPython 3.12）：

uv python install 3.12

uv 会自动从 python-build-standalone 下载预编译的 Python，存放在 ~/.local/share/uv/python/ 目录。

6. 创建 Python 项目

使用 uv init 初始化一个新的 Python 项目，会自动生成 pyproject.toml、README.md 和入口文件 hello.py。

uv init hello-python
cd hello-python

初始化完成后，使用 uv sync 创建虚拟环境并安装依赖：

uv sync

7. 安装项目依赖

uv 提供两种依赖管理模式：

7.1 项目依赖管理（推荐）

使用 uv add 添加依赖，自动写入 pyproject.toml 并锁定版本到 uv.lock：

uv add requests

7.2 pip 兼容模式

uv 也完全兼容 pip 工作流，可以直接替代 pip 安装包：

uv pip install flask

8. 总结