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`