【Python】Python 版本、项目、包、管理工具UV

小溪彼岸
860 阅读4分钟

UV简介

UV 是由 Astral 团队使用 Rust 编写开发的极快速的 Python 包和项目管理工具。它集成了多种常用 Python 工具（如 pip、pip-tools、poetry、pyenv 等）的功能，提供了一个统一的工具来管理项目依赖、环境、脚本和 Python 版本。

UV官网文档：docs.astral.sh/uv/

UV功能

  • 管理 Python 版本，快速切换不同版本
  • 运行和安装 Python 包中的工具
  • 支持单文件脚本的依赖管理和运行

安装

# MacOS and Linux
$ curl -LsSf https://astral.sh/uv/install.sh | sh

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

基本使用

查看帮助文档

在命令行终端输入 uv --help 查看帮助文档

图片

  • run：运行命令或脚本
  • init：创建一个python项目
  • add：添加项目依赖
  • remove：移除项目依赖
  • sync： 更新项目环境
  • lock：更新项目lock文件
  • export：将项目的lock文件导出为其他格式
  • tree：显示项目依赖树
  • tool：运行并安装 Python 包提供的命令
  • python：管理和安装 Python 版本
  • pip：管理与 pip 兼容的界面管理 Python 包
  • venv：创建虚拟环境
  • build：将 Python 包构建为源码分发包和组件
  • publish：将分发包上传到包管理平台
  • cache：管理UV缓存
  • self：管理 uv 可执行文件
  • version：查看uv版本
  • help：帮助命令

创建项目

创建项目格式：uv init 项目名

# 初始化项目，
$ uv init example

# 初始化项目同时指定python版本
$ uv init example -p 3.11.10

创建完成后，将会得到一个如下结构的项目

.
├── .python-version  # 项目使用的python版本 
├── README.md        # 项目描述文件
├── hello.py         
└── pyproject.toml   # 项目配置文件，名称、版本、依赖

项目依赖

  • 添加项目依赖格式： uv add 包名
  • 移除项目依赖格式：uv remove 包名
# 添加项目依赖
$ uv add ruff

# 一次添加多个依赖项
$ uv add ruff httpx

# 向脚本添加隔离依赖项
$ uv add --script example.py requests

# 移除项目依赖
$ uv remove ruff

# 向脚本移除隔离依赖项
$ uv remove --script example.py requests

图片

指定镜像源

常用的指定镜像源的方式有两种，一种是在命令中指定，一种是在项目配置中指定

# 指定默认镜像源为清华源
$ uv add pandas --default-index https://pypi.tuna.tsinghua.edu.cn/simple

# 添加镜像源清华源
$ uv add pandas --index https://pypi.tuna.tsinghua.edu.cn/simple

# 为pip指定默认源为南京大学源
$ uv pip install torch torchvision torchaudio --default-index https://mirror.nju.edu.cn/pytorch/whl/cu126

也可以在项目中的 pyproject.toml 文件中添加如下配置：

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

图片

项目配置

同步项目环境，这对于下载别人的项目和更新、下载依赖库很重要

# 更新项目环境
$ uv sync

# 更新项目lock文件
$ uv lock

# 显示项目依赖树
$ uv tree

# 将项目的lock文件导出为其他格式
$ uv export 

图片

项目及依赖运行

运行依赖库命令

# 运行项目依赖脚本
$ uv run ruff check

图片

运行项目

$ uv run main.py

运行指定Python版本

# 运行指定Python版本
$ uv run --python pypy@3.8 -- python

运行独立脚本(不带pyproject.toml 目录的项目)

$ uv run --no-project example.py

Tools工具

图片

tool命令提供了全局python终端命令的管理：

  • run：运行python包命令，相当于uvx
  • install：安装python包命令，相当于npm、pip
  • uninstall：python包命令
  • upgrade：更新python包命令版本
  • list：查看已安装的python包命令
  • update-shell：确保工具可执行文件目录在 PATH 环境变量中
  • dir：显示uv工具目录的路径
# 运行python包命令
$ uv tool run pycowsay 'hello world!'

# 安装全局命令行
$ uv tool install ruff

# 安装全局命令行
$ uv tool uninstall ruff

# 查看已安装工具列表
$ uv tool list

# 检查可执行目录是否在环境变量中
$ uv tool update-shell

# 查看uv tool安装目录
$ uv tool dir
# 输出结果：/Users/username/.local/share/uv/tools

图片

UVX

uvx类似 pipx 和 npx 用于在临时环境中执行并安装 Python 包提供的命令行工具，uvx是命令 uv tool run 的别名

$ uvx pycowsay 'hello world!' 

图片

Python版本管理

uv 安装 Python 并允许在版本之间快速切换， 命令格式：uv python install python指定版本

# 安装指定版本
$ uv python install 3.10

# 安装多个版本
$ uv python install 3.10 3.11 3.12

# 安装一个替代python实现，例如pypy
$ uv python install pypy@3.10

# 重新安装uv托管的python版本
$ uv python install --reinstall

# 查看可用的python版本
$ uv python list

# 查找已安装的Python的安装路径
$ uv python find 3.10

# 固定当前项目以使用特定的python版本
$ uv python pin 3.12

# 卸载指定python版本
$ uv python uninstall 3.12

Pip依赖包管理

手动管理环境和包 — 旨在用于传统工作流程或高级命令无法提供足够控制的情况

图片

pip命令提供了针对项目的python终端命令的管理：

  • compile：将一个 requirements 文件编译 requirements.txt 文件
  • sync：与 requirements.txt 文件同步环境
  • install：安装python包命令
  • uninstall：卸载python包命令
  • freeze：以 requirements 格式列出环境中安装的包
  • list：以 tabular 格式列出环境中安装的包
  • show：显示一个或多个已安装包的信息
  • tree：显示环境的依赖树
  • check：验证已安装的包具有兼容的依赖项
# 同步安装环境
$ uv pip sync

# 安装python包
$ uv pip install ruff

# 卸载python包
$ uv pip uninstall ruff

# 显示已安装包
$ uv pip freeze

# 显示已安装包
$ uv pip list

# 显示环境的依赖树
$ uv pip tree

Python虚拟环境

创建虚拟环境

# 创建虚拟环境
$ uv venv

# 激活虚拟环境
$ source .venv/bin/activate

# 停用环境
$ deactivate

使用指定Python版本

$ uv venv --python 3.12.0

VU缓存

管理和检查 uv 的状态，例如缓存、存储目录

# 删除缓存条目
$ uv cache clean

# 删除过时的缓存条目
$ uv cache prune

# 显示 uv 缓存目录路径
$ uv cache dir

更新VU

用于更新uv工具自身版本

# 将UV更新到最新版本
$ uv self update

编译发布

uv build 可用于为您的项目构建源代码分发和二进制分发。默认情况下，uv build 将在当前目录中构建项目，并将构建的工件放在 dist/ 子目录中

# 为项目构建包
$ uv build

# 发布包
$ uv publish

简单案例

为Python脚本指定依赖库，在命令行终端执行如下指令

$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
$ uv add --script example.py requests

上面指令会创建一个 example.py 文件并在脚本文件中添加 requests 隔离依赖（该依赖只会在该文件中出现，不会添加到项目配置中）

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "requests",
# ]
# ///
import requests; print(requests.get("https://astral.sh"))

在隔离的虚拟环境中运行脚本

$ uv run example.py

图片

常见问题

uv add、uv pip和uv tool install的区别

  • uv add：用于向当前项目添加依赖，并自动更新 pyproject.toml 文件
  • uv pip：用于管理项目环境中的依赖，提供与 pip 高度兼容的接口，用于手动管理环境中的包，不会更新 pyproject.toml 文件
  • uv tool install：用于全局安装 Python 命令行工具（如 ruff、black 等），类似于 pipx 和 pip install

UV可以管理全局python版本吗？

UV用于指定和管理运行命令行或者项目中的Python版本，不能管理全局Python版本

友情提示

见原文：【Python】Python 版本、项目、包、管理工具UV

本文同步自微信公众号 "程序员小溪" ，这里只是同步，想看及时消息请移步我的公众号，不定时更新我的学习经验。

avatar
文章
阅读
粉丝