uv 日常使用指南
面向 macOS，覆盖安装、Python 版本、项目、依赖、脚本、工具和卸载等日常用法。
1. 一句话理解 uv
uv 可以统一管理 Python 版本、虚拟环境和项目依赖。
使用时记住三点：
- 每个项目使用独立的
.venv。 - 使用
uv add管理依赖，使用uv run运行命令。 - 不要向 macOS 或 Xcode 自带的 Python 安装项目依赖。
2. 安装
使用官方安装脚本：
curl -LsSf https://astral.sh/uv/install.sh | sh
重新打开终端，然后检查：
uv --version
如果仍提示找不到命令，可以执行：
source ~/.zshrc
3. 五分钟创建项目
# 创建并进入项目
uv init demo
cd demo# 固定 Python 版本
uv python pin 3.13# 添加依赖
uv add requests
uv add --dev pytest ruff# 运行程序和测试
uv run main.py
uv run pytest
uv run ruff check .
uv 会自动创建虚拟环境和锁文件，通常不需要手动激活环境。
4. 认识项目文件
| 文件或目录 | 作用 | 提交到 Git |
|---|---|---|
pyproject.toml |
项目信息和依赖声明 | 是 |
uv.lock |
锁定依赖的准确版本 | 是 |
.python-version |
项目使用的 Python 版本 | 通常是 |
.venv/ |
项目的虚拟环境 | 否 |
简单理解：pyproject.toml 说明需要什么，uv.lock 记录最终安装什么，.venv 存放实际环境。
5. 管理 Python 版本
# 查看版本
uv python list
uv python list --only-installed# 安装 Python
uv python install 3.13# 当前项目固定使用 3.13
uv python pin 3.13# 查看实际使用的解释器
uv python find
uv run python --version# 卸载 uv 管理的 Python
uv python uninstall 3.13
如果项目需要的 Python 不存在，uv 通常会自动下载，无需提前手动安装。
6. 管理依赖
# 添加正式依赖
uv add requests# 指定版本范围
uv add 'requests>=2.32,<3'# 添加开发依赖
uv add --dev pytest ruff# 删除依赖
uv remove requests# 查看依赖树
uv tree
升级依赖：
# 只升级一个包
uv lock --upgrade-package requests# 升级全部依赖
uv lock --upgrade
uv add 和 uv remove 会同时更新 pyproject.toml、uv.lock 和 .venv。
7. 运行与同步
# 运行脚本
uv run main.py# 运行模块
uv run python -m http.server 8000# 运行项目工具
uv run pytest
uv run ruff check .# 手动同步环境
uv sync# 只更新锁文件
uv lock
uv run 会先检查锁文件和环境，再执行命令。
通常不需要激活 .venv。如果 IDE 或外部工具要求激活：
uv sync
source .venv/bin/activate
退出环境：
deactivate
CI 中可以严格使用已提交的锁文件：
uv sync --locked
uv run --locked pytest
8. 接手已有项目
uv 项目
项目已有 pyproject.toml 和 uv.lock：
git clone <仓库地址>
cd <项目目录>
uv sync
uv run python main.py
requirements.txt 项目
迁移到 uv 项目模式：
uv init
uv add -r requirements.txt
暂时保持传统 pip 工作方式：
uv venv --python 3.13
source .venv/bin/activate
uv pip install -r requirements.txt
常见兼容命令：
uv pip install flask
uv pip uninstall flask
uv pip list
uv pip check
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
区别：uv add 会维护项目和锁文件；uv pip install 只修改当前虚拟环境。新项目优先使用 uv add。
需要导出传统 requirements 文件时：
uv export --format requirements.txt --output-file requirements.txt
9. 单文件脚本
无第三方依赖：
uv run script.py
临时带依赖运行：
uv run --with requests script.py
让脚本自己记录 Python 版本和依赖：
uv init --script script.py --python 3.13
uv add --script script.py requests rich
uv run script.py
10. Python 命令行工具
临时运行，不长期安装：
uvx ruff check .
uvx ruff@latest check .
长期安装常用工具：
uv tool install ruff
uv tool list
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall ruff
uvx：临时、隔离地运行工具。uv tool install：长期安装全局命令行工具。uv run：在当前项目环境中运行工具。
项目使用的 pytest、ruff 等工具，通常应通过 uv add --dev 加入项目，再使用 uv run。
11. 更新、缓存与卸载
官方脚本安装的 uv 可以自更新：
uv self update
查看和清理缓存：
uv cache dir
uv cache clean
完全卸载：
uv cache clean
rm -rf "$(uv python dir)"
rm -rf "$(uv tool dir)"
rm -f "$HOME/.local/bin/uv" "$HOME/.local/bin/uvx"
rm -rf "$HOME/.config/uv" "$HOME/.local/share/uv" "$HOME/.local/state/uv"
不要删除整个 ~/.local/bin，其中可能还有其他软件。
12. 常见问题
每次都要激活 .venv 吗？
不需要。直接使用 uv run <命令>。
.venv 损坏怎么办？
rm -rf .venv
uv sync
如何确认使用的是哪个 Python？
uv python find
uv run python -c 'import sys; print(sys.executable)'
哪些文件应该提交？
提交 pyproject.toml、uv.lock 和通常情况下的 .python-version；不要提交 .venv/。
为什么 uv 自动下载 Python？
项目需要的版本不存在时，uv 默认会自动安装兼容版本，这是正常行为。
13. 命令速查
| 目的 | 命令 |
|---|---|
| 创建项目 | uv init demo |
| 固定 Python | uv python pin 3.13 |
| 添加依赖 | uv add requests |
| 添加开发依赖 | uv add --dev pytest |
| 删除依赖 | uv remove requests |
| 同步环境 | uv sync |
| 运行程序 | uv run main.py |
| 运行测试 | uv run pytest |
| 查看依赖树 | uv tree |
| 升级一个包 | uv lock --upgrade-package requests |
| 临时运行工具 | uvx ruff check . |
| 创建虚拟环境 | uv venv --python 3.13 |
| 更新 uv | uv self update |
| 清理缓存 | uv cache clean |
推荐习惯
- 不向系统或 Xcode Python 安装项目依赖。
- 每个项目使用独立
.venv。 - 提交
pyproject.toml和uv.lock，不提交.venv。 - 依赖管理优先使用
uv add，运行命令优先使用uv run。 - 升级依赖后运行测试，再提交新的
uv.lock。
官方资料
- uv 官方文档
- 安装与卸载
- 项目管理
- Python 版本管理
- 命令行工具