Python 版本和项目管理工具 uv 的基本用法

uv 日常使用指南

面向 macOS，覆盖安装、Python 版本、项目、依赖、脚本、工具和卸载等日常用法。

1. 一句话理解 uv

uv 可以统一管理 Python 版本、虚拟环境和项目依赖。

使用时记住三点：

  1. 每个项目使用独立的 .venv。
  2. 使用 uv add 管理依赖，使用 uv run 运行命令。
  3. 不要向 macOS 或 Xcode 自带的 Python 安装项目依赖。

2. 安装

使用官方安装脚本：

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

使用 HomeBrew 安装：

brew install uv

重新打开终端，然后检查：

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

推荐习惯

  1. 不向系统或 Xcode Python 安装项目依赖。
  2. 每个项目使用独立 .venv。
  3. 提交 pyproject.toml 和 uv.lock，不提交 .venv。
  4. 依赖管理优先使用 uv add，运行命令优先使用 uv run。
  5. 升级依赖后运行测试，再提交新的 uv.lock。

官方资料

posted @ 2026-06-22 23:47  江南烟雨梦  阅读(92)  评论(0)    收藏  举报