uv 使用手册：Python 版本与项目管理工具入门
uv 是由 Astral（也就是 ruff 的开发团队）用 Rust 编写的一款超快 Python 包与项目管理工具。它可以一个工具替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具，并且速度通常比传统工具快 10～100 倍。
目录
一、uv 能做什么
| 功能 | 替代的工具 |
| --- | --- |
| 安装/切换 Python 版本 | pyenv |
| 创建虚拟环境 | virtualenv、venv |
| 安装/锁定依赖 | pip、pip-tools、poetry |
| 运行单文件脚本（自动管理依赖） | pipx、手动 venv |
| 安装全局 Python 工具 | pipx |
一句话总结：只要你开始一个新的 Python 项目，先敲 uv init 就对了。
二、安装与配置
2.1 安装 uv
uv 支持 macOS、Linux 和 Windows，下面给出最常用的几种安装方式。
方式一：官方安装脚本（macOS / Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh
安装完成后，脚本会提示把 uv 加入当前 Shell 环境变量。一般执行下面命令让当前终端立即生效：
source $HOME/.local/bin/env方式二：Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"方式三：使用 pip 安装
如果你已经有一个 Python 环境，也可以直接当普通包安装：
pip install uv方式四：Homebrew（macOS）
brew install uv2.2 验证安装
uv --version能看到版本号（例如 uv 0.x.x）就说明安装成功。
2.3 基础配置（可选）
uv 的大部分行为可以通过环境变量或配置文件（项目根目录的 uv.toml 或用户级的 ~/.config/uv/uv.toml）控制。几个新手常用的配置：
# uv.toml —— 放在项目根目录
[tool.uv]
# 指定国内镜像源，加速依赖下载（以清华源为例）
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# 安装依赖时自动生成并遵守 uv.lock 锁文件
lock = true提示：如果在国内网络环境，配置镜像源能显著提升下载速度。也可以直接用环境变量：
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
三、基础使用
3.1 管理 Python 版本
uv 可以帮你下载并管理多个 Python 版本，无需单独安装 pyenv。
# 查看当前可用的 Python 版本
uv python list
# 安装某个指定版本的 Python（例如 3.12）
uv python install 3.12
# 为当前项目固定使用 Python 3.11
uv python pin 3.11
# 查看项目实际使用的 Python 路径
uv python find运行 uv python pin 3.11 后，项目根目录会生成一个 .python-version 文件，之后在该目录下执行 uv 命令都会自动使用对应版本。
3.2 创建与管理项目
创建新项目
# 在当前目录初始化一个项目
uv init my-project
# 进入项目
cd my-projectuv init 会生成以下文件：
my-project/
├── .python-version # 锁定的 Python 版本
├── README.md
├── main.py # 示例入口文件
├── pyproject.toml # 项目元数据与依赖声明
└── uv.lock # 依赖锁文件（首次同步后生成）添加依赖
# 添加运行时依赖（例如 requests）
uv add requests
# 添加开发依赖（例如 pytest）
uv add --dev pytest
# 移除依赖
uv remove requests每执行一次 uv add，uv 都会自动更新 pyproject.toml 和 uv.lock，并创建/更新虚拟环境（默认在 .venv）。
同步环境
# 根据 pyproject.toml + uv.lock 安装/更新环境
uv sync在虚拟环境中运行命令
# 在项目的虚拟环境中执行任意命令
uv run python main.py
uv run pytest经验法则：凡是需要在项目环境里跑的命令，前面都加
uv run，这样就不用手动source .venv/bin/activate了。
3.3 运行脚本
uv 支持在单文件脚本顶部用 PEP 723 的内联元数据声明依赖，运行时会自动创建临时虚拟环境并安装依赖，特别适合写小工具/实验脚本。
# hello.py
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "requests",
# ]
# ///
import requests
resp = requests.get("https://www.baidu.com")
print("状态码:", resp.status_code)直接运行，无需手动建环境：
uv run hello.py3.4 安装命令行工具
想全局安装一个用 Python 写的命令行工具（类似 pipx）：
# 安装一个全局可用的工具，例如 httpie
uv tool install httpie
# 临时运行某个工具（不污染全局环境）
uvx ruff check .uvx 等价于 uv tool run，适合临时跑一下某个工具。
四、完整示例
下面用一个从 0 到 1 的小项目，串联上面的所有命令。
步骤 1：初始化项目
uv init weather-cli
cd weather-cli步骤 2：添加依赖
uv add requests此时 pyproject.toml 内容类似：
[project]
name = "weather-cli"
version = "0.1.0"
description = "一个演示 uv 用法的天气查询小工具"
requires-python = ">=3.10"
dependencies = [
"requests>=2.32.3",
]步骤 3：编写代码（main.py）
import requests
def get_weather(city: str) -> str:
# 这里仅为示例，实际使用请替换为真实 API 与密钥
url = f"https://wttr.in/{city}?format=3"
resp = requests.get(url, timeout=10)
resp.raise_for_status()
return resp.text.strip()
if __name__ == "__main__":
city = input("请输入城市名（英文）：")
print(get_weather(city))步骤 4：运行项目
uv run python main.py步骤 5：添加开发依赖并测试
uv add --dev pytest新建 test_main.py：
from main import get_weather
def test_get_weather():
result = get_weather("Beijing")
assert isinstance(result, str)
assert len(result) > 0运行测试：
uv run pytest步骤 6：固定并分享环境
把项目提交到 Git 时，uv.lock 会一起提交。别人拿到代码后只需：
uv sync就能复现完全一致的依赖环境，无需关心平台差异。
五、常见问题
Q1：uv 命令找不到？
多半是安装后没有刷新环境变量。请重新打开终端，或执行：
source $HOME/.local/bin/env # macOS / LinuxWindows 用户请确认安装脚本提示的目录已加入 PATH。
Q2：如何彻底删除 uv 创建的虚拟环境？
直接删除项目里的 .venv 目录即可，对系统没有任何影响：
rm -rf .venv需要时再 uv sync 重建。
Q3：和已有的 pip / venv 工作流冲突吗？
不冲突。uv 默认只在自己管理的项目目录内创建 .venv，不会影响系统 Python 或其他工具的全局环境。你可以把它理解为更现代、更快的替代品。
Q4：如何升级 uv 本身？
uv self updateQ5：国内下载慢怎么办？
参考 2.3 基础配置 配置国内镜像源即可。
小结
- 安装：
curl -LsSf https://astral.sh/uv/install.sh | sh - 初始化项目：
uv init - 加依赖：
uv add 包名 - 跑命令：
uv run 命令 - 复现环境：
uv sync
掌握上面这几条，你就已经能覆盖 90% 的日常 Python 开发场景了。更多高级用法（如工作区、私有源、构建发布等）可以查阅 官方文档。
