Python——uv工具的使用

整体说明

  • uv 是一个快速的 Python 包管理器和项目管理工具，由 Astral 公司开发，旨在替代 pip、venv 等工具，提供更快的安装速度和更简洁的使用体验
  • uv 通常比 pip 快 10-100 倍
  • uv 内置虚拟环境：无需单独管理虚拟环境
  • uv 支持项目管理：原生支持 pyproject.toml，详情见附录
  • uv 保持了与 pip 相似的命令行接口，对于熟悉 pip 的用户来说很容易上手，同时提供了更现代、更高效的功能

安装 uv

  • 安装 uv 工具：

    1
    2
    3
    4
    5
    # 使用 pip 安装
    pip install uv

    # 或者使用官方安装脚本（推荐）
    curl -LsSf https://astral.sh/uv/install.sh | sh

  • 安装完成后，可以通过 uv --version 验证是否安装成功

  • 若提示没有命令，可能是需要配置环境变量，将下面的命令添加到 ~/.bashrc 中即可：

    1
    source $HOME/.local/bin/env

uv 基本用法介绍

虚拟环境管理

  • uv 内置了虚拟环境管理功能，无需单独使用 venv 或 virtualenv：

    1
    2
    3
    4
    5
    6
    7
    # 创建并激活虚拟环境（会在当前目录创建 `.venv` 文件夹）
    uv venv
    source .venv/bin/activate  # Linux/macOS 激活环境，切换到当前环境下
    deactivate # Linux/macOS 退出激活

    # 直接在虚拟环境中运行命令（无需手动激活）
    uv run python --version

  • 若使用 source .venv/bin/activate 激活环境

    • 像 conda 一样，会切换到指定的虚拟环境下，直接使用 which python 可访问到当前项目的 python 文件
    • 但此时 pip 不会像 conda 一样替换，还是需要使用 uv pip 来使用，直接使用 which pip 得到的还是通用的 pip

IDEA 环境配置

  • 在使用 uv venv 创建了虚拟环境以后，可以使用 IDEA 直接选择 ./.venv/bin/python 作为解释器

类似 pip 的包安装与管理

  • uv 可以像 pip 一样安装和管理 Python 包： 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    # 安装包
    uv pip install requests

    # 安装特定版本的包
    uv pip install requests==2.31.0

    # 从requirements.txt安装
    uv pip install -r requirements.txt

    # 升级包
    uv pip install --upgrade requests

    # 卸载包
    uv pip uninstall requests

    # 查看已安装的包
    uv pip list

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

uv 运行 python 文件

  • 使用 uv run 可以在虚拟环境中直接运行命令，无需手动激活环境 ：

    1
    2
    3
    4
    5
    6
    7
    8
    # 运行Python解释器
    uv run python

    # 运行脚本
    uv run script.py

    # 运行命令行工具（如pytest）
    uv run pytest tests/

  • 常用命令 uv run --locked：

    • --locked 是一个“断言锁文件是最新的”检查开关，强制要求 uv.lock 必须与 pyproject.toml 完全同步
      • 若不同步则直接报错退出，不会自动更新锁文件
        • **不加 --locked**：uv 在运行前通常会默默检查依赖，如果发现锁文件过时，它可能会自动更新 uv.lock（或提示你更新），然后继续执行
        • 加 --locked**：宁可报错，也绝不自动修改锁文件** ，是一种保护机制
    • 会检查以下内容
      • 执行 uv run --locked <命令> 时，uv 会对比项目配置文件（pyproject.toml 或 uv.toml）和锁文件（uv.lock）
        • 如果 pyproject.toml 里的依赖和 uv.lock 里记录的完全一致，则 命令正常执行
        • 如果 pyproject.toml 里的依赖有变动，但 uv.lock 还没更新 则 命令直接报错 ，不会运行后面的命令

  • 常用命令 uv run --frozen（与 --locked 比较）：

    • --locked：检查 pyproject.toml 和 uv.lock 是否匹配（不匹配就报错）
    • --frozen：完全不读取 pyproject.toml，只认 uv.lock，即使 pyproject.toml 改了也忽略它

附录：uv 高级功能

缓存管理

  • uv 具有高效的缓存机制，可以手动管理缓存： 
    1
    2
    3
    4
    5
    # 清理缓存
    uv cache clean

    # 查看缓存大小
    uv cache size

配置镜像源

  • uv 可以配置自己的 pip 源，配置国内镜像源加快下载速度，比如：

    1
    2
    # 设置 PyPI 镜像源
    export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/
    • 注：也可以永久添加到环境变量中方便使用

  • 临时指定镜像源的方式为：

    1
    uv add <package> --index-url https://pypi.tuna.tsinghua.edu.cn/simple/

  • 安装时输出源信息：

    1
    uv add requests --verbose # 注意：谨慎打开 `--verbose` 这个参数，会输出特别长的日志

构建和发布包

  • uv 支持构建和发布 Python 包到 PyPI： 
    1
    2
    3
    4
    5
    # 构建包
    uv build

    # 发布包到 PyPI
    uv publish

附录：uv 管理 python 项目

  • uv 支持现代 Python 项目管理，包括 pyproject.toml： 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    # 初始化新项目（创建 pyproject.toml）
    uv init my_project # 在当前目录下创建 my_project 文件夹并生成基本文件
    # 生成 README.md	main.py		pyproject.toml 等文件
    cd my_project

    # 添加依赖（会更新 pyproject.toml）
    uv add requests  # 生产依赖，将 requests 添加到 pyproject.toml 的 dependencies 列表中同时安装 requests 及其依赖（注：requests 的依赖不会添加到 pyproject.toml 中）
    uv add --dev pytest  # 开发依赖，仅开发阶段需要使用到的依赖（将 pytest 添加到 pyproject.toml 的 dev 列表中），pytest 就是最常见的开发依赖，prod 环境不需要

    # 安装项目依赖（根据 pyproject.toml）
    uv sync # 补充：uv sync 是一个“按锁同步”的命令，它会根据 uv.lock 文件来安装精确版本的依赖，它不会重新解析依赖或修改 uv.lock 文件，详情见附录

    # 运行项目中的脚本
    uv run my_script.py

补充：pyproject.toml 介绍

  • pyproject.toml 是现代 Python 项目的核心配置文件（TOML 格式）
    • 由 PEP 517/518/621 标准化
    • 可 替代传统的 setup.py/setup.cfg/requirements.txt
    • 实现统一管理项目构建、依赖、工具与元数据
pyproject.toml 的核心作用

  • 构建系统声明 ：指定项目用什么工具构建（如 setuptools/hatch），解决“如何打包”的问题

    1
    2
    3
    [build-system]
    requires = ["setuptools>=61.0"]
    build-backend = "setuptools.build_meta"

  • 项目元数据 ：定义项目名、版本、作者、描述、入口点等，用于发布与识别

  • 依赖管理 ：声明运行/开发依赖（替代 requirements.txt），支持版本约束与分组

    1
    2
    3
    4
    [project]
    dependencies = ["torch>=2.0", "numpy"]
    [project.group.dev]
    dependencies = ["pytest", "black"]

  • 工具配置 ：存放 uv/poetry/pytest 等工具的专属配置（[tool.xxx]）

  • 注：这 相当于 Node.js 的 package.json ，是项目的“配置中枢”

uv run xx.py 在执行什么

  • uv run xx.py 是 uv 工具的脚本执行命令 ，核心是在 uv 管理的隔离环境中运行 Python 脚本 ，背后做 3 件事：
    • 1）环境准备 ：读取 pyproject.toml/uv.lock，确保依赖已安装（自动执行 uv sync 逻辑），并激活对应虚拟环境
    • 2）脚本执行 ：调用 Python 解释器运行 xx.py，等价于 uv run python xx.py
    • 3）参数透传 ：脚本后的所有参数直接传给 xx.py，和原生 python 一致
  • 相当于传统 Python 项目的什么命令
    uv 命令 传统 Python 等价操作（手动流程） 说明
    uv run xx.py 1. 激活虚拟环境（source venv/bin/activate）
    2. python xx.py    		 uv 自动完成环境激活与依赖校验
    uv run python xx.py python xx.py（已激活虚拟环境） 完全等价
    uv run --frozen xx.py 跳过依赖检查，直接运行 对应部署场景的快速执行
  • TLDR： uv run xx.py ≈ 自动激活虚拟环境 + python xx.py ，省去手动管理虚拟环境的步骤

补充：uv lock 命令详解

  • uv lock 是 uv 的依赖解析引擎
    • 不会安装任何包，而是根据 pyproject.toml 中声明的约束条件，计算出所有依赖的精确版本和哈希值，并将这个确定性的依赖关系树写入 uv.lock 文件
  • uv lock 的详细执行步骤
    • 1）读取项目清单 (pyproject.toml) ：解析项目直接依赖项（dependencies）、可选依赖项（optional-dependencies）、开发依赖项及项目元数据（如 requires-python）
    • 2）构建依赖图并解析冲突（核心） ：
      • 获取所有直接依赖及其传递依赖（子依赖）
      • 根据 requires-python（Python 版本范围）过滤掉不兼容的包版本
      • 运行高级求解算法（类似于 pip-compile 但更快），解决版本冲突
        • 例如，如果 A 需要 B>1.0，而 C 需要 B<2.0，求解器会找到满足所有条件的版本（如 B=1.5）
    • 3）获取元数据（索引查询） ：
      • 查询配置的 PyPI 镜像（或私有源），获取每个候选包的元数据（版本号、发布时间、依赖项、支持的系统平台等）
      • 如果需要，还会拉取 Git 仓库或本地路径包的元数据
    • 4）锁定平台特定标记（跨平台支持） ：
      • uv 默认生成通用锁文件（Universal Locking）
      • 它会计算包在不同系统（Windows/Linux/macOS）上的 Wheels 兼容性（即 sys_platform 和 implementation_name 标记），确保锁文件在所有开发者机器和 CI/CD 环境上通用
      • 注意：这里是计算所有平台上的版本，也就是说解析后对所有平台都通用（可以理解为每个包的所有版本信息）
    • 5）确定精确版本 ：为每个包选出符合约束条件的最新兼容版本（除非指定升级策略），这保证了项目所有成员安装的是同一个版本
    • 6）计算文件哈希（完整性校验） ：计算每个锁定包的分发文件（Wheel 或源码包）的哈希值（SHA-256），并将其写入锁文件，以防止恶意篡改或源数据意外变更
    • 7）写入 uv.lock 文件 ：将上一步生成的完整依赖树、精确版本、哈希值以及解析源（PyPI URL 或 Git 地址）以结构化格式写入 uv.lock
      • 后续将这个文件也上传到云端，可以保证每个用户安装的都是相同的版本
  • 常用选项与高级场景
    选项 作用
    uv lock --upgrade 升级所有依赖 ：忽略 uv.lock 中现有的锁定版本，重新查找符合 pyproject.toml 约束的最新版本
    uv lock --upgrade-package <PACKAGE> 升级特定包 ：仅针对指定的包进行升级，其余依赖保持锁定的版本不变
    uv lock --python-platform <PLATFORM> 锁定特定平台 ：例如 --python-platform windows，用于为特定操作系统（如 Linux 服务器）生成锁文件，即使在 macOS 上开发
    uv lock --extra <EXTRA> 包含可选依赖 ：将指定的可选依赖组纳入解析范围（常用于确保 dev 组和主依赖无冲突）
    uv lock --no-update 仅检查不更新 ：如果 uv.lock 已存在且与 pyproject.toml 一致，则直接退出；若不一致则报错，而不生成新锁文件（常用于 CI 检查）

补充：uv sync 命令详解

  • uv lock 是制定施工蓝图 ，而 uv sync 是按蓝图施工
    • uv lock ：只负责解析 ，根据 pyproject.toml 计算出所有依赖的精确版本，并写入 uv.lock 文件。它不会安装任何包
    • uv sync ：只负责安装 ，读取现有的 uv.lock 文件，并将环境同步到该状态。它不会修改 uv.lock 文件
  • uv sync 用于将项目的虚拟环境与锁文件 (uv.lock) 的状态同步一致
    • 理解：可以把它看作一个更智能、更快速的 pip install -r requirements.txt + pip install -e .
  • uv sync 是一个“按锁同步”的命令，它会根据 uv.lock 文件来安装精确版本的依赖
    • 注意：它不会 重新解析依赖或修改 uv.lock 文件
  • uv sync 的详细执行步骤
    • 1）读取配置与检查环境 ：从项目根目录的 pyproject.toml 中读取项目配置
      • 同时检查是否存在虚拟环境（默认是 .venv/），如果不存在则自动创建
    • 2）读取锁文件 (uv.lock) ：读取 uv.lock 文件，获取需要安装的每一个包的精确版本号
      • 如果 uv.lock 不存在，uv sync 会自动执行 uv lock 来生成它
    • 3）安装依赖包 ：根据 uv.lock 的内容，安装项目所需的所有依赖包。此步骤会：
      • 默认包含开发依赖 ：会安装 [project.optional-dependencies] 中定义的所有可选依赖组，包括开发依赖（如 --dev 组）
      • 以可编辑模式安装项目 ：将项目本身 以可编辑（-e）模式安装到虚拟环境中
        • 这意味着你对项目代码的修改会立即生效，无需重新安装
    • 4）执行“精确”同步（清理多余包） ：这是 uv sync 的一个重要特性
      • 默认情况下，它会执行 “精确”同步 ，包括删除不必要的包
      • 这意味着，如果虚拟环境中存在任何不在 uv.lock 中的包 ，uv sync 会将其移除 ，以确保环境与锁文件完全一致
  • 常用选项与场景
    • uv sync --frozen：生产环境部署或需要绝对确定性时使用
      • 此命令不会检查或更新锁文件，直接根据现有的 uv.lock 安装
    • uv sync --no-dev：当不需要开发依赖时（如在生产环境）使用
      • 此命令会排除开发依赖的安装
    • uv sync --no-editable：当你不想以可编辑模式安装项目时使用
      • 项目会被正常安装，修改代码后需要重新执行 uv sync 才能生效
    • uv sync --inexact：当你希望保留环境中已有的、但不在锁文件中的额外包时使用
      • 此命令会跳过移除多余包的操作
    • uv sync --extra <EXTRA>：安装指定的可选依赖组时使用
      • 例如 uv sync --extra dev 或 uv sync --extra test
    • uv sync --all-packages：在大型项目（monorepo）中，需要同步工作区内所有子项目的依赖时使用