uv 使用速查与实战笔记

一、uv 是什么

uv 是一个由 Rust 编写的高速 Python 包与项目管理工具，由 Astral（Ruff 的开发商）推出。

它的目标是成为 Python 领域的“一站式工具”，整合并替代以下常见工具的核心功能：

pip（安装依赖）
poetry / pipenv（项目与依赖管理）
pip-tools（锁文件）
pyenv（Python 版本管理）
virtualenv / venv（虚拟环境）
pipx（CLI 工具管理）

核心优势只有一句话：快，而且简单。

二、安装 uv

推荐使用官方独立安装方式。

macOS / Linux

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

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

说明：

不依赖系统 Python
不需要安装 Rust
会自动下载并管理 Python

三、uv 的四种典型使用场景

场景 A：正式 Python 项目（替代 Poetry / Pipenv）

适用于：

长期维护项目
有明确依赖管理需求
需要锁版本、可复现环境

1. 初始化项目

uv init crypto-checker
cd crypto-checker

生成内容包括：

pyproject.toml：项目与依赖配置
uv.lock：依赖锁文件
.python-version：Python 版本锁定
示例 Python 文件

2. 添加依赖

uv add httpx rich

uv 会自动：

创建 .venv 虚拟环境
安装依赖
写入 pyproject.toml
生成或更新 uv.lock

3. 编写代码（示例）

import httpx
from rich.console import Console
from rich.panel import Panel


def main():
    console = Console()
    url = "https://api.coindesk.com/v1/bpi/currentprice.json"

    with console.status("正在获取比特币价格..."):
        response = httpx.get(url, timeout=10.0)
        response.raise_for_status()
        data = response.json()
        price = data["bpi"]["USD"]["rate"]

    console.print(
        Panel(
            f"Bitcoin Price: ${price}",
            title="Crypto Checker",
        )
    )


if __name__ == "__main__":
    main()

4. 运行项目

uv run hello.py

说明：

不需要手动激活虚拟环境
uv 会自动使用 .venv

5. 同步环境（给同事 / 新机器）

uv sync

uv 会严格根据 uv.lock 还原环境。

场景 B：单文件脚本（PEP 723 脚本依赖）

适用于：

临时脚本
运维 / 数据处理
不想创建项目目录

1. 创建脚本并声明依赖

echo 'print("Hello")' > weather.py
uv add --script weather.py requests

脚本会被自动改写为：

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
# ]
# ///
print("Hello")

2. 完整示例

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
# ]
# ///
import requests

resp = requests.get("https://wttr.in/Shanghai?format=3")
print(f"当前天气: {resp.text}")

3. 运行脚本

uv run weather.py

特点：

不创建 .venv
在缓存目录创建隔离环境
可复用、但不污染当前目录

场景 C：CLI 工具（替代 pipx）

1. 临时运行工具（uvx）

uvx pycowsay "uv is fast!"

说明：

首次运行会下载工具
会缓存隔离环境
下次运行直接复用

缓存位置通常在：

~/.cache/uv/

2. 安装常用工具

uv tool install ruff

安装到用户级别
不污染系统 Python

场景 D：Python 版本管理（替代 pyenv）

安装 Python

uv python install 3.12

固定项目 Python 版本

uv python pin 3.11

会生成 .python-version 文件。

四、最常用命令速查

命令	作用
`uv init`	创建项目
`uv add <pkg>`	添加依赖
`uv run <cmd>`	在环境中运行
`uv sync`	同步依赖
`uvx <tool>`	临时运行工具
`uv tool install`	安装 CLI 工具
`uv python install`	安装 Python

五、使用心得总结

项目用 uv init / uv add / uv run
脚本用 PEP 723 + uv run
CLI 工具用 uvx / uv tool install
不再手动管理 venv
不再纠结 Python 版本

一句话总结：

uv 把 Python 开发中“环境、依赖、工具”这三件最烦的事，统一成了一套又快又干净的工作流。