UV Python 包管理器

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

**Windows (PowerShell)**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装结束后，重启终端或执行 source $HOME/.cargo/env（Unix）使其生效。

通过 pip 安装

如果你已有 Python 环境，也可通过 pip 安装：

pip install uv

验证安装：

uv --version

基础概念速览

UV 提供了以下核心子命令，覆盖从解释器到依赖的全生命周期：

第一个 UV 项目

创建项目目录并初始化

mkdir my-uv-project && cd my-uv-project
uv init

该命令会生成 pyproject.toml、.python-version 和一个基础的 hello.py 示例文件。UV 项目本质上就是标准化的 Python 项目，未来可以灵活扩展到各类框架。

指定 Python 版本

uv python install 3.12

UV 会自动下载并管理该版本解释器。项目中可通过 .python-version 固定版本，成员协作时统一开发环境。

创建虚拟环境

uv venv

UV 会使用 .python-version 指定的解释器创建 .venv 虚拟环境。无需事先激活，因为后续命令会自动识别并使用该环境。

使用 UV 管理依赖

添加依赖包

uv add requests flask

执行后，依赖会写入 pyproject.toml 的 dependencies 列表，同时解析并生成 uv.lock 锁定文件；依赖包直接安装至当前虚拟环境。

区分开发依赖

uv add --dev pytest black

开发依赖会记录在 [tool.uv.dev-dependencies] 中，不影响生产环境。

移除依赖

uv remove flask

安装项目所有依赖（同步）

当从版本库拉取包含 pyproject.toml 和 uv.lock 的项目后，执行：

uv sync

uv sync 会根据锁定文件精准重现依赖树，并自动将当前项目的包以可编辑模式（-e .）安装，确保团队成员和环境完全一致。

锁定文件与依赖锁定

UV 生成的 uv.lock 是一个跨平台的、内容可哈希的锁定文件。它记录了所有包的确切版本、哈希值与环境标记，保证可重现构建。

常用操作：

• 手动更新锁定文件：uv lock
• 升级某依赖到最新并同步：uv add --upgrade requests
• 查看依赖树：uv tree

锁定文件的哲学：记录解析结果而非锁定单一平台，与 poetry.lock 类似，但 UV 在解析速度和正确性上进行了深度优化。

运行脚本和命令

在项目环境中执行脚本

无需手动激活虚拟环境，只需使用：

uv run python myscript.py

uv run 会自动使用 .venv 中的解释器，如果环境不存在还会自动创建。运行命令行工具同样简单：

uv run pytest

直接运行内联脚本（又名 UV 脚本）

UV 支持带有元数据的 Python 脚本头部声明，实现单文件依赖运行：

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.12"
# dependencies = ["requests>=2.28"]
# ///
import requests
print(requests.get("https://httpbin.org/get").json())

保存文件后给予执行权限，可直接运行。UV 会在内部自动创建临时环境并安装依赖。

全局工具管理 (uv tool)

uv tool 提供了与 pipx 相似的体验，用于安装和管理全局可用的命令行工具。

安装一个工具：

uv tool install ruff

运行一个工具（不安装，直接执行）：

uv tool run ruff check .

列出、更新、卸载：

uv tool list
uv tool upgrade ruff
uv tool uninstall ruff

工具被安装在隔离的环境中，互不干扰。

高级工作流技巧

强制使用系统 Python

如果想用系统解释器而非自动下载的，可在命令前加 --python-preference only-system，或设置环境变量 UV_PYTHON_PREFERENCE=only-system。

跨平台依赖锁定

UV 支持为不同平台/ Python 版本生成交叉锁定。在 pyproject.toml 中声明所需支持的标记：

[tool.uv]
environments = ["python_version >= '3.10'", "sys_platform == 'linux'"]

之后 uv lock 会生成包含所有兼容环境下的包版本，使 uv.lock 真正跨平台。

从 pip 工作流迁移

对于老项目，可直接使用 uv pip 子命令（兼容 pip 接口）：

uv pip install -r requirements.txt
uv pip freeze > requirements_lock.txt

当准备好迁移时，只用 uv add 逐个添加现有依赖即可享受锁定同步的便利。

常见问题与排错

Q: UV 创建环境或安装包时提示网络错误？ 确保系统代理或网络正常，UV 默认使用 PyPI 官方源。可设置 UV_INDEX_URL 环境变量指定镜像。

Q: uv sync 提示找不到匹配的 Python 解释器？ 使用 uv python install 3.x 安装所需版本，并确认 .python-version 中版本号正确。

Q: 如何彻底清除 UV 的缓存？

uv cache clean

Q: 可以使用私有 PyPI 源吗？ 在 pyproject.toml 中配置：

[tool.uv]
extra-index-url = ["https://my-private-index/simple"]