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 高级功能

缓存管理

  • 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 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 ，省去手动管理虚拟环境的步骤