UV – установка и настройка пакетного менеджера Python

В этой статье мы расскажем о UV (Universal Virtualenv) – менеджере пакетов и проектов Python, написанном на Rust.

Главное преимущество UV – скорость работы. Благодаря UV вы можете установить зависимости проекта или указанную версию Python буквально за считанные секунды. Разработчики отмечают, что UV в 10–100 раз быстрее pip.

Источник: docs.astral.sh/uv/

Однако скорость – не единственное преимущество: пакетный менеджер UV также объединяет в себе ряд инструментов, таких как pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv и другие.

Установка UV 

Для установки UV в Linux загрузите установщик с официального сайта:

wget https://astral.sh/uv/install.sh

Теперь необходимо сделать файл исполняемым:

chmod +x install.sh

Запустите установку:

./install.sh

Чтобы команды uv и uvx стали доступны, обновите переменные:

source $HOME/.local/bin/env

Проверим корректность установки:

$ uv -V
uv 0.8.24

Обновление UV 

Обновить UV вы можете следующим образом:

uv self update

Очистка кэша UV 

Скорость работы UV во многом обусловлена хранением файлов версий Python или зависимостей в кэше. Однако если кэш занимает слишком много места, вы можете очистить его:

uv cache clean

Установка версий Python

UV позволяет быстро выполнить установку Python. Чтобы посмотреть версии Python (установленные и доступные к установке), выполните команду:

uv python list

Чтобы посмотреть только установленные версии, в конце команды добавьте флаг --only-installed:

$ uv python list --only-installed
cpython-3.12.3-linux-x86_64-gnu    /usr/bin/python3.12
cpython-3.12.3-linux-x86_64-gnu    /usr/bin/python3 -> python3.12

Для установки последней версии Python выполните команду:

uv python install

Если нужно установить определенную версию, укажите ее номер, например:

$ uv python install 3.13
Installed Python 3.13.7 in 3.92s
 + cpython-3.13.7-linux-x86_64-gnu (python3.13)

Переустановка Python

Так как в дистрибутивы Python различных версий регулярно добавляются улучшения, исправляющие баги, вы можете переустановить все версии Python:

uv python install --reinstall

Либо переустановить конкретную версию:

uv python install --reinstall 3.13

Использование UV в качестве замены pip и virtualenv

UV может быть использован как полная замена таких утилит, как pip, pip-tools и virtualenv. Главное преимущество – команды остаются те же, вам не нужно запоминать новые и менять ваши рабочие процессы. При этом скорость и удобство работы с модулями и пакетами в Python, а также зависимостями и версиями существенно возрастают.

Сперва создайте виртуальное окружение:

uv venv

Менеджер пакетов uv умеет работать с виртуальным окружением самостоятельно, поэтому вам необязательно активировать его вручную. Установим пакет:

uv pip install django

Проверяем:

$ uv pip list
Package  Version
-------- -------
asgiref  3.10.0
django   5.2.7
sqlparse 0.5.3

Удалить пакет можно с помощью uv pip uninstall:

$ uv pip uninstall django
Uninstalled 1 package in 303ms
 - django==5.2.7

Если нужно удалить несколько пакетов, перечислите их через пробел:

uv pip uninstall <пакет1> <пакет2>

UV не только включает в себя функционал популярных Python-инструментов, но и обладает собственным функционалом, который мы рассмотрим далее.

Работа с проектами с помощью UV 

Рассмотрим создание нового проекта и миграцию существующего в UV.

Создание проекта

Для создания проекта выполните команду uv init <name-dir>, указав желаемое имя проекта. Чтобы инициализировать проект в текущей директории, выполните uv init.

Далее перейдите в созданный каталог проекта:

$ uv init beget-test
Initialized project beget-test at /home/ltfrost/beget-test
$ cd beget-test

UV создаст в каталоге файлы, необходимые для управления проектом, а после первого запуска создаст виртуальное окружение и файл uv.lock – lockfile, содержащий всю информацию о зависимостях проекта.

Вы можете закрепить за проектом определенную версию Python, например:

uv python pin 3.13

Чтобы запустить скрипт, выполните команду uv run:

Миграция проекта в UV 

Для того чтобы работать с зависимостями существующего проекта, необходимо выполнить миграцию. Команда uvx migrate-to-uv позволяет выполнить миграцию проектов, созданных следующими инструментами:

•     Poetry;
•     Pipenv;
•     pip-tools;
•     pip.

Если ваша работа с пакетами Python включает использование pip, сперва выгрузите список зависимостей в файл requirements.txt, после чего выполните команду:

$ uvx migrate-to-uv
Locking dependencies with "uv lock"...
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.11`.
Resolved 9 packages in 6ms
Successfully migrated project from pip to uv!

Список зависимостей был загружен в файл uv.lock, проект успешно мигрировал и теперь может управляться с помощью UV. В качестве минимальной версии Python была установлена версия 3.11, изменить ее можно в файле uv.lock (также отредактируйте строку requires-python в файле pyproject.toml).

Управление зависимостями

Установка и удаление пакетов

Для добавления зависимости в проект используйте команду uv add. Информация о зависимостях будет обновлена в файле pyproject.toml, а также в lockfile и виртуальном окружении:

uv add django

Вы можете также указать конкретную версию пакета:

uv add 'django==5.2.5'

Для удаления зависимости используйте uv remove.

Обновление пакетов

При развертывании проекта будут установлены зависимости тех же версий, что использовались в проекте на момент создания lockfile. UV позволяет обновить как все используемые зависимости, так и каждую по отдельности. Сперва посмотрим список зависимостей, для которых доступны новые версии:

$ uv tree --outdated
Using CPython 3.9.23
warning: No `requires-python` value found in the workspace. Defaulting to `>=3.9`.
Resolved 9 packages in 1ms
 v0.0.1
├── asgiref v3.6.0 (latest: v3.10.0)
├── django v4.2.4 (latest: v4.2.25)
│   ├── asgiref v3.6.0
│   └── sqlparse v0.4.4 (latest: v0.5.3)

Обновить можно как отдельный пакет:

uv lock --upgrade-package <имя-пакета>

Так и все пакеты, для которых доступны обновления:

uv lock --upgrade

Затем загрузите новые версии пакетов:

uv sync

Pylock.toml

В качестве замены файла requirements.txt был утвержден новый формат, хранящий информацию о зависимостях, – pylock.toml. Файл не привязан к конкретному инструменту – он может быть создан UV и использоваться другими инструментами (и наоборот). 

Чтобы преобразовать uv.lock в pylock.toml, выполните команду:

uv export -o pylock.toml

Теперь при переносе вы можете развернуть проект из pylock.toml:

uv pip install -r pylock.toml

Если возникнут вопросы, напишите нам, пожалуйста, тикет из панели управления аккаунта (раздел “Помощь и поддержка”), а если вы захотите обсудить управление пакетами Python или пообщаться о наших продуктах с коллегами по цеху и сотрудниками Beget – ждем вас в нашем сообществе в Telegram.