uv使用心得

uv 全指南：下一代 Python 项目管理利器

1. 简介与安装

uv 是一个由 Rust 编写的极速 Python 包管理器。它旨在统一 Python 碎片化的工具链，用一个工具替代 pip、poetry、virtualenv、pip-tools 和 pyenv。

核心优势： * 快：比 pip 快 10-100 倍。 * 省：全局缓存机制，同一版本的包只需下载一次。 * 全：一个命令搞定 Python 版本管理、虚拟环境、依赖解析。

安装方式

macOS / Linux:

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

Windows (PowerShell):

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

安装后验证：

uv --version

2. 从项目出发，如何使用uv？

接下来，我们将使用 uv 最推荐的现代开发模式，围绕 pyproject.toml 进行一个python项目的创建、管理和运行。

2.1 初始化项目

# 创建新项目目录
mkdir my-project
cd my-project

# 初始化
uv init --python 3.12

这会生成 pyproject.toml（配置文件）、.python-version（指定 python 版本）和 hello.py。

2.2 配置文件 pyproject.toml

uv init 生成的文件遵循标准 PEP 621 规范。

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

[tool.uv]
package = true  # 【关键】告诉 uv 将当前项目视为一个可安装的包

2.3 管理依赖 (add, remove)

忘掉 pip install，使用以下命令会自动更新配置文件和 uv.lock。

• 添加依赖：

  uv add httpx            # 添加最新版
  uv add "pandas<2.0"     # 添加指定版本范围

• 添加开发依赖 (仅开发时需要，如测试、格式化工具)：

  uv add --dev pytest ruff

• 移除依赖：

  uv remove httpx

  特性：remove 会自动从虚拟环境中卸载该包，保持环境清洁。

2.4 运行代码 (run) —— 核心亮点

uv run 是智能执行器，它会自动检测并挂载虚拟环境，你永远不需要手动激活环境。

• 基础运行：

  uv run hello.py         # 运行脚本
  uv run python           # 进入 Python 交互式环境
  uv run pytest           # 运行测试工具

• 【进阶】解决“找不到模块”与脚本路径问题： 当你有一个复杂的项目结构（如 app/ 存代码，script/ 存脚本）时，直接运行脚本常报错。

  最佳实践配置： 如果你的项目是扁平结构（Flat Layout，即源码文件夹直接放在根目录），请在 pyproject.toml 添加以下配置，明确告诉工具哪些是你的代码包：

  [tool.setuptools.packages.find]
  where = ["."]
  include = ["app*", "llm*"]  # 将你的源码目录名填在这里
  exclude = ["script*", "log*", "data*"]

  运行效果： 执行一次 uv sync 后，无论你在哪里，都可以轻松运行脚本且不报错：

  cd script
  # uv 会自动找到根目录环境，并将 app/ 加入路径
  uv run init_db.py

2.5 同步环境 (sync)

当发生以下情况时，使用 sync： 1. 刚 git clone 了一个新项目。 2. 手动修改了 pyproject.toml 文件。 3. 切换了 git 分支，导致依赖变更。

uv sync

它会确保你的 .venv（虚拟环境）与 uv.lock（锁定文件）完全一致。

• CI/CD 模式：uv sync --frozen（如果 lock 文件与 toml 不匹配则报错，防止意外升级）。

2.6 兼容模式 (pip)

如果你需要处理旧项目，或者只需要最底层的安装功能：

# 仅安装包，不修改 pyproject.toml
uv pip install numpy

# 导出依赖
uv pip freeze > requirements.txt

---

3. 其他实用命令

3.1 全局工具管理 (tool)

替代 pipx。用于安装需要在命令行全局使用的工具（如 black, ipython）。

• 临时运行 (推荐)：

  # 下载 ruff，检查代码，然后清理，不占硬盘
  uvx ruff check .

• 永久安装：

  uv tool install mypy
  # 之后可以直接在终端运行 mypy

3.2 依赖树查看 (tree)

查看当前项目的依赖关系树，排查冲突神器。

uv tree

输出示例：

my-project v0.1.0
├── httpx v0.27.0
│   ├── anyio v4.3.0
│   └── httpcore v1.0.5
└── pandas v2.2.1
    └── numpy v1.26.4

3.3 Python 版本管理 (python)

替代 pyenv。uv 可以帮你下载和管理 Python 解释器。

• 列出可用版本：

  uv python list

• 安装特定版本：

  uv python install 3.11

• 锁定项目版本：

  # 在项目目录下运行，会修改 .python-version 文件
  uv python pin 3.11