新一代Python包与项目管理工具——UV

文章目录

简介
特点
安装
升级
- 独立安装
- PyPI安装
卸载
uv常用功能介绍

简介

uv是由Astral开发的一个开源项目，是用Rust编写的极速Python包与项目管理工具。Astral同时还开发了Ruff和ty工具，其公司官网为Astral

特点

可以取代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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS和Linux

以下两种方法任选其一，看你的系统支持哪个工具，一般都支持curl

复制代码

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

PyPI安装

为了方便，uv发布了PyPI，使用pipx install uv或pip install uv即可安装

其他安装方式

除了上面两种安装方式，uv还支持Homebrew、WinGet、Scoop、Docker、GitHub Releases、Cargo的安装方式，参见uv的官方文档

升级

独立安装

使用独立安装方式的可直接使用以下命令进行更新

uv self update

PyPI安装

使用PyPI安装方式的可使用以下命令进行更新

pip install --upgrade uv

卸载

如果你不想使uv了，可以使用以下方式进行卸载

清除存储数据(可选)

shell 复制代码

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

移除uv、uvx和uvw的二进制文件

Windows

shell 复制代码

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

macOS和Linux

shell 复制代码

rm ~/.local/bin/uv ~/.local/bin/uvx

uv常用功能介绍

uv是一个比较强大的工具，其提供项目管理、脚本管理、工具管理及运行、Python版本管理、Python包管理(通过pip接口)、虚拟环境管理(通过virtualenv)等功能，下面对几个本人常用的功能做下记录，其他功能如有需要，可到官方文档中查看

Python版本管理

Python版本安装

uv支持安装不同的Python版本，并可以快速在不同版本中切换

复制代码

uv python install 3.10 3.11 3.12

如果之前系统中没有安装过对应的Python版本，uv会自动下载对应的Python版本。如果只想安装一个版本，如安装3.10，把后面的3.11和3.12删除即可

切换Python版本

若要切换Python版本，可以使用以下命令

uv python pin 3.12

注意使用这个命令时，uv会将Python版本写入.python-version文件中，如果没有这个文件，uv会报错并退出。如果命令中没有提供版本号，uv会自动查找已有的.python-version文件，并显示当前固定的版本号。

查看可用的Python版本

使用以下命令，可查已安装和可用的Python版本

uv python list

如果后面带上版本号，如uv python list 3.13则会筛选出所有3.13的Python版本

升级Python版本

使用uv升级Python版本时，只支持由uv管理的Python，其他管理工具的无法使用uv升级，并且仅支持补丁版本升级，即3.13.4到3.13.5可以自动升级，3.12到3.13无法使用uv自动升级，升级命令如下

shell 复制代码

uv python upgrade 3.13

若要升级所有Python版本，可以使用以下命令

shell 复制代码

uv python upgrade

注意，uv不支持降版本，即3.13.5到3.13.4，只能先删除3.13.5，再安装3.13.4

卸载Python版本

如果不想使用该版本Python了，或者想降级Python小版本，就需要卸载Python版本

shell 复制代码

uv python uninstall 3.10

重新安装Python

若Python受到了污染，需要重新安装Python来解决一些问题时，可以使用命令

shell 复制代码

uv python install --reinstall

创建虚拟环境

创建虚拟环境本应该和pip接口放一起，因为这个是代替Python自带的创建虚拟环境（venv和virtualenv）方法的，但这个功能可能更常用，有时候我们可能不会用uv的项目管理功能（如果用项目管理功能，会自动创建虚拟环境），或者需要创建指定版本的Python虚拟环境时，会经常用到这个命令

shell 复制代码

uv venv

默认创建的路径为当前目录下的.venv文件夹中，如果需要更换文件夹名，可使用命令

shell 复制代码

uv venv .venv_py_3.13

默认这个命令创建到虚拟环境为当前固定的Python版本，如果需要创建其他Python版本，可使用命令

shell 复制代码

uv venv .venv_py_3.10 --python 3.10

项目管理

创建项目

uv还有一个比较实用的功能，就是可以帮你自动创建Python项目，使用命令

shell 复制代码

uv init hello-world

或者先创建文件夹再创建项目

shell 复制代码

mkdir hello-world
cd hello-world
uv init

如果使用第一个一行的命令，则会自动创建一个hello-world文件夹，如果先创建文件夹后，进入到这个文件夹，再执行命令，效果也是一样的

使用uv init创建的项目，其项目结构如下

shell 复制代码

├── .git/    --git版本记录的文件夹
├── .gitignore    --git中需要忽略的内容
├── .python-version    --用于uv记录Python版本的文件
├── pyproject.toml    --项目信息文件
├── README.md    --项目的说明文件
└── src    --代码源文件存放的目录
    └── hello_world    --自动创建的以项目名称命名的文件夹
        └── __init__.py    --自动创建的初始化py文件

第一次运行项目

创建好项目后，uv可以直接运行该项目，以刚才的hello-world为例

shell 复制代码

cd hello-world
uv run hello-world

当运行过一次项目，会发现项目的目录结构有所变化，如下所示

shell 复制代码

.
├── .git/
├── .venv/    --自动创建的Python虚拟环境
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .gitignore
├── .python-version
├── README.md
├── src
│   └── hello_world
│       └── __init__.py
├── pyproject.toml
└── uv.lock    --可跨平台使用的项目依赖说明，由uv管理，不需要手动编辑

管理项目依赖包

uv直接提供项目的依赖包管理，包括添加、删除、同步、冻结，以运行一个简单的Flask网站为例，说明下如何使用uv进行依赖管理

添加依赖 add

shell 复制代码

uv add requests flask

使用上面的命令，可以在当前项目中添加上requests、flask两个依赖包，也可以使用uv add 'requests==2.31.0'去指定使用的依赖版本，如果要直接有requirements.txt文件，也可以使用uv add -r requirements.txt -c constraints.txt直接从文件迁移依赖

删除依赖 remove

shell 复制代码

uv remove requests

冻结 lock
冻结（lock）可创建项目依赖的说明文件，即uv.lock

shell 复制代码

uv lock

如果还没有uv.lock文件，可以使用这个命令创建，如果已经有了，则该命令不会起作用，但是当你加上--upgrade参数时，就会起作用，会升级所有依赖到最新的版本

当只需要升级某个包时，可以使用

shell 复制代码

uv lock --upgrade-package requests

或

shell 复制代码

uv lock -P requests

同步 sync
同步（Syncing）可确保所有项目依赖均已安装，并且与锁定文件（lockfile）保持一致

shell 复制代码

uv sync

其作用就是在当前项目中，确保所有环境都已更新，然后再去激活虚拟环境运行代码，一般很少用到，只有运行他人项目或迁移项目时会用到

打包 build
uv提供为项目打包的功能，可直接生成二进制的发布文件和源文件，放在当前目录下的dist文件夹中

shell 复制代码

uv build

发布 publish
使用发布命令可以将打包好的文件发布到包管理平台，一般是PyPI

shell 复制代码

uv publish dist

该命令只需要指定到文件路径

pip接口

uv还提供的一个常用功能就是pip接口功能，这是一个非常常用的功能，因为并不是所有人都会使用uv做为管理工具，那我们使用uv的人如何给他们同步我们的项目呢？当然是使用pip，因为这是Python默认到依赖管理工具，即便没有uv，也可以使用pip去管理依赖（除了部分精简Python版本，可能不提供pip），使用方法可以说和pip没有任何区别，只需要你在pip命令前加个uv

shell 复制代码

uv pip install requests
uv pip show requests
uv pip freeze >> requirements.txt
uv pip check
uv pip list
uv pip uninstall requests
uv pip tree

上面的命令从上到下依次是安装包、查看包、冻结包、检查当前环境的兼容包、列出所有已经安装的包、卸载包、查看当前环境的依赖树

工具的使用

大部分Python包提供应用程序供直接调用命令，uv则提供了运行和安装这些工具的接口，可直接在命令行运行或安装工具

临时运行工具

uv提供了一个命令uvx，可以直接运行工具而不用安装，比如要使用ruff工具，这个是一个Rust语言开发的Python极速代码检查工具，也是由Astral公司开发的，相当于Black(格式化工具) + Flake8(检查器) + isort(排序和格式化) + pyupgrade(代码升级工具)的合体

shell 复制代码

uvx ruff

这个命令等同于uv tool run ruff，比如在使用ruff时，要查看ruff版本，就可以使用命令

shell 复制代码

uvx ruff -V

安装本地工具

如果工具经常要使用，可以将其安装到本地后，直接调用，使用命令

shell 复制代码

uv tool install ruff

这个命令将会在当前的工作目录中创建一个虚拟环境，当卸载工具时会自动删除，如果手动删除环境，工具将无法运行

工具安装好后，就可以直接使用ruff -V查看ruff版本了

运行脚本

独立运行脚本

uv可以直接独立运行一个Python脚本，并支持传参，比如创建一个test.py文件，内容如下

python 复制代码

import os
print(os.path.expanduser("~"))

然后我们使用命令

shell 复制代码

uv run test.py hello world!

就可以直接运行脚本文件了，输出结果就是hello world!

按需带依赖运行脚本

在运行Python脚本时，所需的依赖是必须要提前安装的，否则会报错，但使用uv运行脚本时，更倾向于按需创建环境，比如脚本中需要使用到requests依赖，使用下面命令

shell 复制代码

uv run --with requests test.py

可以在运行脚本是再添加依赖，但是要注意，如果直接在项目运行，这些依赖也会添加到项目中，如果不想添加到项目中，记得带上参数--no-project，另外如果需要多个依赖，可以重复使用--with参数

声明脚本依赖

uv支持添加或更新脚本metadata，使用命令uv add --script即可添加，示例如下

shell 复制代码

uv add --script example.py 'requests<3' 'rich'

python 复制代码

# /// 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运行的时候会安装script的生命创建环境，同样也可以通过script声明Python版本

以上就是对uv的一些介绍，也是常用的一些功能，更多详细的内容请参见uv的官方指导手册