uv 常用命令整理

安装与验证

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

# 验证安装
uv --version

# 更新 uv 自身
uv self update

项目初始化

# 初始化新项目（创建项目目录并生成 pyproject.toml 等文件）
uv init my_project

# 进入项目目录
cd my_project

依赖管理

# 添加依赖（会更新 pyproject.toml 和锁文件）
uv add requests
uv add "fastapi>=0.68.0"

# 添加开发依赖
uv add --dev pytest

# 移除依赖
uv remove requests

# 同步环境（根据 pyproject.toml 和 uv.lock 安装或更新依赖）
uv sync

# 导出依赖到 requirements.txt 格式
uv export > requirements.txt

虚拟环境管理

# 创建虚拟环境（默认生成 .venv 目录）
uv venv

# 指定 Python 版本创建环境
uv venv --python 3.11

# 激活环境（Linux/macOS）
source .venv/bin/activate

# 激活环境（Windows PowerShell）
.venv\Scripts\Activate.ps1

# 退出环境
deactivate

Python 版本管理

# 安装指定版本的 Python 解释器
uv python install 3.12

# 查看已安装的 Python 版本
uv python list

# 为当前项目指定 Python 版本（生成 .python-version 文件）
uv python pin 3.11

高级包管理（兼容 pip 命令）

# 使用 uv pip 安装包（兼容 pip 语法，速度更快）
uv pip install -r requirements.txt

# 编译生成锁定的依赖文件
uv pip compile requirements.in -o requirements.txt

# 根据锁定文件精确同步环境
uv pip sync requirements.txt

# 查看依赖树
uv tree

工具运行与全局工具

# 在项目环境中运行命令（自动处理环境）
uv run python script.py

# 运行临时工具（类似 pipx，无需预先安装）
uvx cowsay "Hello UV!"

# 全局安装 CLI 工具
uv tool install black

# 运行全局工具
uv tool run black .

实用技巧

# 配置国内镜像源（以清华源为例，可大幅提升下载速度）
uv add --default-index https://pypi.tuna.tsinghua.edu.cn/simple requests

# 清理缓存
uv cache clean

# 查看帮助
uv help