【基础】Python包管理工具uv使用全教程

一、uv简介

uv 是由 Astral(前身为 Basis)团队开发的 Python 包安装器和解析器,完全使用 Rust 语言编写。与传统 Python 工具不同,uv 将多个工具的功能整合到一个高性能的解决方案中,旨在提供更现代、更高效的 Python 开发体验。

底层技术原理

uv 之所以能够实现显著的性能提升,主要基于几个关键技术:

  1. Rust 实现:利用 Rust 语言的内存安全和高性能特性,避免了 Python 自身的解释开销
  2. 并行处理:在依赖解析和包下载安装过程中大量使用并行处理
  3. 优化的缓存策略:智能缓存机制减少重复下载和编译
  4. 零拷贝设计:减少内存使用和系统调用
  5. 编译优化:对于需要编译的包,采用更高效的编译策略

uv性能

uv一个极快的 Python 包和项目管理器,用 Rust 编写,有多快呢,看图说话:

突出特点

​🚀 一款工具,可替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等,并更多。

⚡️ 比 pip 快 10-100 倍 。

🗂️ 提供全面的项目管理 ,具有 通用的锁文件 。

❇️ 运行脚本 ,支持 内联依赖元数据 .

🐍 安装和管理 Python 版本。

🛠️ 运行和安装 发布为 Python 包的工具。

🔩 包含一个 与 pip 兼容的接口 ,以熟悉的 CLI 提升性能。

🏢 支持 Cargo 风格的工作区 ,适用于可扩展的项目。

💾 磁盘空间高效,具有全局缓存以进行依赖项去重。

⏬ 无需 Rust 或 Python,通过 curl 或 pip 即可安装。

🖥️ 支持 macOS、Linux 和 Windows。

二、安装

不同环境安装

根据你的操作系统,选择安装方式,Windows安装,需要powershell。

复制代码
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 
# With pip.
pip install uv

#如果你支持pipx,也可以安装到隔离环境中
pipx install uv

执行界面:

注:dos窗口重新打开,才能开到更新的环境变量,才能使用新安装的uv工具。

另:如果需要更多安装方式或者卸载,见:https://docs.astral.sh/uv/getting-started/installation/#pypi

查看版本

要检查已安装的版本:

复制代码
uv version

以下内容也有效:

  • uv --version # Same output as `uv version`
  • uv -V # Will not include the build commit and date
  • uv pip --version # Can be used with a subcommand

三、uv功能

uv 为 Python 开发提供必要功能------从安装 Python 和编写简单的脚本到处理支持多个 Python 版本和平台的复杂项目。

3.1 Python 版本管理

Python 版本由 Python 解释器(即 python 可执行文件)、标准库和其他支持文件组成。安装和管理 Python 本身。

  • uv python install:安装 Python 版本。
  • uv python list:查看可用的 Python 版本。
  • uv python find:查找已安装的 Python 版本。
  • uv python pin:将当前项目固定到使用特定 Python 版本。
  • uv python uninstall:卸载 Python 版本。

命令示例:

复制代码
uv python list  # 查看uv支持的python版本
 
uv python install 3.10 3.11 3.12 # 安装指定版本的Python
 
uv python find 3.10  # 查找特定版本的python
 
uv python uninstall 3.10  # 卸载特定版本的python
 
uv run --python 3.12 python  # 指定版本运行python交互界面
uv run -p 3.12 python  # 指定版本运行python交互界面
uv run --python [email protected] python
uv run -p [email protected] python
 
uv python pin 3.11  # 在当前目录中使用特定的 Python 版本

3.2 运行脚本

运行无依赖项的脚本

执行独立的 Python 脚本,例如 example.py

example.py

print("Hello world")

执行它:

如果您的脚本依赖于 standard 库中的模块,也不需要安装依赖,执行命令是一样的。

如果需要向脚本提供参数,如:

example.py

import sys print(" ".join(sys.argv[1:]))

执行效果:

此外,您可以直接从 stdin 读取您的脚本:

复制代码
$ echo 'print("hello world!")' | uv run -

注意,如果你在一个项目中 使用 uv run,即一个带有 pyproject.toml 的目录,它会在运行脚本之前进行安装。如果您的脚本不依赖于项目,可以使用 --no-project 标志跳过此步骤:

复制代码
# Note: the `--no-project` flag must be provided _before_ the script name.
uv run --no-project example.py

运行有依赖项的脚本

当您的脚本需要其他软件包时,必须将它们安装到 脚本运行环境中。可以使用 pyproject.toml管理依赖,uv会在执行脚步前进行安装。同时, UV 也支持每次调用请求依赖项。

例如,以下脚本需要 rich

example.py

复制代码
import time
from rich.progress import track

for i in track(range(20), description="For example:"):
    time.sleep(0.05)

使用 --with 选项请求依赖项:

复制代码
$ uv run --with rich example.py

执行效果:

如果需要特定版本,可以将 constraints 添加到请求的依赖项中:

复制代码
$ uv run --with 'rich>12,<13' example.py

可以通过使用 --with 选项重复来请求多个依赖项。

运动带有Python内置依赖

如果python脚本,在脚本本身中声明脚本的依赖项,用--script参数执行。

以下是包含嵌入元数据的脚本示例:

复制代码
# /// script
# requires-python = "\>=3.11"
# dependencies = \[
# "requests\<3",
# "rich",
# \]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint(\[(k, v\["title"\]) for k, v in data.items()\]\[:10\])

使用 uv init --script 使用内联元数据初始化脚本, 它允许选择 Python 版本和定义依赖项:

复制代码
uv init --script example.py --python 3.12

UV 支持为您添加和更新内联脚本元数据。使用 uv add --script 声明脚本的依赖项:

复制代码
uv add --script example.py 'requests<3' 'rich'

这将在脚本顶部添加一个脚本部分,使用 TOML 声明依赖项:

example.py

复制代码
# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

命令一览表

  • uv run:运行脚本。
  • uv add --script:向脚本添加依赖。
  • uv remove --script: 从脚本中移除依赖

3.3 虚拟环境管理

创建虚拟环境

UV 支持创建虚拟环境,例如,在 .venv 中创建虚拟环境:

复制代码
uv venv

可以指定特定的名称或路径,例如,在 my-name 处创建虚拟环境:

复制代码
uv venv my-name

可以请求 Python 版本,例如,使用 Python 3.11 创建虚拟环境:

复制代码
uv venv --python 3.11

使用虚拟环境

使用默认虚拟环境名称时,uv 将在后续调用期间自动查找并使用虚拟环境。

复制代码
uv venv

# Install a package in the new virtual environment
uv pip install ruff

可以 "激活" 虚拟环境以使其软件包可用:

复制代码
#Windows
.venv(环境所在目录,就是环境名)\Scripts\activate

#macOS and Linux
#终端类型:fish,执行
source .venv/bin/activate
#终端类型:csh/tcsh,执行
source .venv/bin/activate.csh
#终端类型:Nushell,执行
use .venv\Scripts\activate.nu

退出环境

要退出虚拟环境,请使用 deactivate 命令:

复制代码
deactivate

使用任意 Python 环境

由于 uv 不依赖于 Python,因此它可以安装到自己的虚拟环境中。例如,设置 VIRTUAL_ENV=/path/to/venv 将导致 uv 安装到 /path/to/venv 中,无论之前 uv 安装在何处。请注意,如果 VIRTUAL_ENV 设置为 不是符合 PEP 405 的虚拟环境,它将被忽略。

UV 还可以安装到任意甚至非虚拟环境中,只需向 uv pip sync 或 uv pip install 提供 --python 参数即可。例如 uv pip install --python /path/to/python 将安装到链接到 /path/to/python 解释器。

为方便起见,uv pip install --system 将安装到系统 Python 环境中。用 --system 大致等同于 uv pip install --python $(which python) 。

uv 本身不依赖于 Python,但它确实需要找到一个 Python 环境来 (1) 将依赖项安装到环境中,以及 (2) 构建源代码分发。

发现 Python 环境

当运行改变环境的命令(如 uv pip sync 或 uv pip install)时,uv 将按以下顺序搜索虚拟环境:

  • 基于 VIRTUAL_ENV 环境变量的已激活虚拟环境。
  • 基于 CONDA_PREFIX 环境变量的已激活 Conda 环境。
  • 当前目录或最近的父目录中 .venv 的虚拟环境。
  • 如果未找到虚拟环境,uv 将提示用户通过 uv venv 在当前目录中创建一个虚拟环境。

3.4 兼容pip

UV 提供了常见 pippip-toolsvirtualenv 命令的直接替代品。这些命令直接与虚拟环境一起使用,而 uv 的主界面则自动管理虚拟环境。uv pip 向尚未准备好从 pippip-tools 过渡的高级用户和项目展示了 uv 的速度和功能。

在环境中管理包(替换 pip 和 pipdeptree):

  • uv pip install:将包安装到当前环境。
  • uv pip show:显示已安装包的详细信息。
  • uv pip freeze:列出已安装的包及其版本。
  • uv pip check:检查当前环境是否有兼容的包。
  • uv pip list:列出已安装的包。
  • uv pip uninstall:卸载包。
  • uv pip tree:查看环境的依赖树。

锁定环境中的包(替换 pip-tools):

  • uv pip compile:将需求编译到锁文件中。
  • uv pip sync: 使用锁文件同步环境。

重要提示:这些命令和原pip命令不完全一致,具体使用时,需进一步阅读手册。

3.5 包管理

安装软件包

要将软件包安装到虚拟环境中,例如 Flask:

复制代码
uv pip install flask

要安装启用了可选依赖项的包,例如,带有 "dotenv" extra 的 Flask:

复制代码
uv pip install "flask[dotenv]"

要安装多个软件包,例如 Flask 和 Ruff:

复制代码
uv pip install flask ruff

要安装带有约束的包,例如 Ruff v0.2.0 或更高版本:

复制代码
uv pip install 'ruff>=0.2.0'

要从磁盘安装软件包:

复制代码
uv pip install "ruff @ ./projects/ruff"

要从 GitHub 安装包:

复制代码
uv pip install "git+https://github.com/astral-sh/ruff"

要在特定引用处从 GitHub 安装包,请执行以下作:

复制代码
# Install a tag
uv pip install "git+https://github.com/astral-sh/[email protected]"

# Install a commit
uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"

# Install a branch
uv pip install "git+https://github.com/astral-sh/ruff@main"

从文件安装软件

可以从标准文件格式一次安装多个软件包。

从 requirements.txt 文件安装:

复制代码
uv pip install -r requirements.txt

从 pyproject.toml 文件安装:

复制代码
uv pip install -r pyproject.toml

卸载软件包

要卸载包,例如 Flask:

复制代码
uv pip uninstall flask

要卸载多个软件包,例如 Flask 和 Ruff:

复制代码
uv pip uninstall flask ruff

3.6 项目

uv 支持管理 Python 项目,这些项目在 pyproject.toml 文件中定义它们的依赖项。

创建新项目

您可以使用 uv init 命令创建新的 Python 项目:

复制代码
uv init hello-world
cd hello-world

或者,您可以在工作目录中初始化一个项目:

复制代码
mkdir hello-world
cd hello-world
uv init

UV 将创建以下文件:

.

├── .python-version

├── README.md

├── main.py

└── pyproject.toml

main.py 文件包含一个简单的 "Hello world" 程序。用 uv run 试试:

复制代码
uv run main.py

项目结构

项目由几个重要的部分组成,这些部分协同工作并允许 uv 管理您的项目。除了 uv init 创建的文件外,uv 在你第一次执行项目命令,即 uv run, uv sync或uv lock时,会在项目根目录中,创建一个虚拟环境和 uv.lock 文件 。

完整的列表如下所示:

.

├── .venv

│ ├── bin

│ ├── lib

│ └── pyvenv.cfg

├── .python-version

├── README.md

├── main.py

├── pyproject.toml

└── uv.lock

pyproject.toml 文件

pyproject.toml 包含有关项目的元数据:

pyproject.toml 文件

复制代码
[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

您将使用此文件指定依赖项,以及有关工程的详细信息,例如其描述或许可证。您可以手动编辑此文件,也可以使用 uv add 和 UV Remove 从终端管理您的项目。

命令一览表:

  • uv init: 创建新的 Python 项目。
  • uv add: 向项目添加依赖。
  • uv remove: 从项目中移除依赖。
  • uv sync: 将项目的依赖与环境同步。
  • uv lock: 为项目的依赖创建锁文件。
  • uv run:在项目环境中运行命令。
  • uv tree:查看项目的依赖树。
  • uv build:将项目构建为分发存档。
  • uv publish:将项目发布到包索引。

3.7 工具(tool)

UV 包括一个用于与工具交互的功能。可以使用 uv tool run 在不安装的情况下调用工具,uv提供的uvx命令,和uv tool run 这两个命令完全等效。

如果经常使用某个工具,使用 uv tool install 安装,安装后除非卸载该工具,否则不会删除环境。

工作原理

默认情况下,uv 工具目录名为 tools,位于 uv 应用程序目录中,例如 ~/.local/share/uv/tools。

使用uvx/uv tool run 运行工具时,虚拟环境将存储在 uv 缓存目录中,并被视为一次性环境,即,如果运行 uv cache clean,环境将被删除。

使用 uv tool install 安装工具时,将在 uv tools 目录中创建一个虚拟环境。除非卸载该工具,否则不会删除环境。如果手动删除环境,该工具将无法运行。

命令一览表

  • uvx / uv tool run :在临时环境中运行工具。
  • uv tool install :全局安装工具。
  • uv tool uninstall :卸载工具。
  • uv tool list :列出已安装的工具。
  • uv tool update-shell:更新 shell 以包含工具可执行文件。

3.8 构建和发布包

uv 支持通过 uv build 将 Python 包构建到源代码和二进制分发中,并使用 UV publish 将它们上传到注册表。

准备要打包的项目,必须构建 Python 项目才能安装,此过程通常称为 "打包"。Python 项目元数据在 pyproject.toml 文件。

构建包

使用 uv build 构建包:

复制代码
uv build

默认情况下,uv build 将在当前目录中构建项目,并将构建的工件放在 dist/ 子目录中。

发布包

使用 uv publish 发布包:

复制代码
uv publish

使用 --token 或 UV_PUBLISH_TOKEN 设置 PyPI 令牌,PyPI 不再支持使用用户名和密码进行发布,而是需要生成令牌。

安装软件包

测试是否可以使用 uv run 安装和导入包:

复制代码
uv run --with <PACKAGE> --no-project -- python -c "import <PACKAGE>"

--no-project 标志用于避免从本地项目目录安装软件包。

3.9 应用

管理和检查 uv 的状态,例如缓存、存储目录或执行自我更新:

  • uv cache clean :删除缓存条目。
  • uv cache prune:删除过时的缓存条目。
  • uv cache dir:显示 uv 缓存目录路径。
  • uv tool dir:显示 uv 工具目录路径。
  • uv python dir:显示 uv 安装的 Python 版本路径。
  • uv self update :将 uv 更新到最新版本。

3.10 帮助菜单

--help 标志可用于查看命令的帮助菜单,例如,对于 uv:

复制代码
uv --help

要查看特定命令的帮助菜单,例如 uv init:

复制代码
uv init --help

使用 --help 标志时,uv 会显示一个精简的帮助菜单。要查看命令的较长帮助菜单,请使用 uv 帮助 :

复制代码
uv help

要查看特定命令的长帮助菜单,例如 uv init:

复制代码
uv help init

当使用较长的帮助菜单时,uv 将尝试使用更少或更多的 "page" 输出,以便它不会一次全部显示。要退出寻呼机,请按 q。

四、uvx运行时工具

许多 Python 包都提供了可用作工具的应用程序。UV 具有专门的支持,uvx 命令可以调用工具而不安装,使用 uvx 时,工具会被安装到临时的、隔离的环境中,和uv tool run 这两个命令完全等效。

例如,要运行 ruff:

复制代码
uvx ruff

这正是等价的:

复制代码
uv tool run ruff

五、官方参考

官方文档:https://docs.astral.sh/uv/

相关推荐
Python智慧行囊3 分钟前
前端三大件--HTML
css·python
派阿喵搞电子1 小时前
yolov8中的python基础--模块导入篇
开发语言·python·pygame
qianqianaao1 小时前
实验六 基于Python的数字图像压缩算法
开发语言·图像处理·python·opencv·计算机视觉·自然语言处理·php
一点.点1 小时前
李沐动手深度学习(pycharm中运行笔记)——09.softmax回归+图像分类数据集+从零实现+简洁实现
pytorch·笔记·python·深度学习·动手深度学习·softmax回归
ElenaYu2 小时前
homebrew安装配置Python(MAC版)
开发语言·python·macos
广药门徒2 小时前
配置指定地址的conda虚拟Python环境
开发语言·python·conda
伊织code2 小时前
AWS MCP Servers
服务器·python·ai·云计算·aws·mcp
疯狂学习GIS3 小时前
Python的ArcPy基于Excel表格对大量遥感影像批量重分类
python·arcpy·批处理·遥感数据·遥感影像·重分类·栅格重分类
半路_出家ren3 小时前
Python操作MySQL
开发语言·python·计算机网络·mysql·网络安全
有人说风轻的像雨3 小时前
使用 Python 监控系统资源
python