Быстрый старт в мир Python окружений с uv23.01.2025 06:15

uv — относительно новый и динамично развивающийся инструмент, упрощающий создание и управление Python окружениями. Быстро, без лишних настроек и с простым интерфейсом

uv — довольно быстрый пакетный менеджер и менеджер виртуальных окружений для Python, написанный на Rust. По заявлению разработчиков, uv способен заменить такие Python инструменты, как pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv и другие.

Установка uv

Установка uv с помощью pip

Если вы предпочитаете классический способ установки uv через pip из PYPI:

pip install uv

Иные способы установки uv

Cargo:

cargo install --git https://github.com/astral-sh/uv uv

Homebrew:

brew install uv

Winget:

winget install --id=astral-sh.uv  -e

Scoop:

scoop install main/uv

Более детально про установку можно ознакомиться тут: Installing uv

Проверка установленной версии uv

uv --version

Обновление uv

Если uv был установлен через автономный установщик, обновить его можно следующим образом:

uv self update

Если uv был установлен через pip:

pip install --upgrade uv

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

Создаём новый проект и переходим в директорию:

uv init venv
cd venv

uv init создаёт директорию venv и размещает в ней файлы проекта. cd venv перемещаемся в новосозданную директорию.

Альтернативно, можно создать директорию и внутри неё запустить uv init:

mkdir venv
cd venv
uv init

Содержимое директории после создания проекта:

.gitignore
.python-version
hello.py
pyproject.toml
README.md

Файл .python-version содержит информацию о версии Python, используемой в проекте по умолчанию. Эта версия аналогична той, которая была установлена в системе на момент создания окружения. Файл pyproject.toml содержит информацию об установленных зависимостях:

[project]
name = "venv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

dependencies пока пуст. Он будет наполняться по ходу установки пакетов. Посмотрим на него ещё раз, но попозже.

Запуск Python-скриптов

Внутри директории venv лежит файл hello.py, который при запуске выведет Hello from venv!. Используем его для запуска изнутри нашего окружения:

uv run hello.py

uv run — это команда для инлайн-запуска Python-скрпитов без необходимости вручную активировать и деактивировать виртуальное окружение. При выполнении uv run команды, uv автоматически активирует виртуальное окружение, а после завершения работы скрипта деактивирует его.

При первом запуске команды uv run, внутри venv будет создана директория .venv, содержащая устанавливаемые зависимости, используемые в окружении. Помимо этого, будет создан кроссплатформенный uv.lock файл.

.venv
.gitignore
.python-version
hello.py
pyproject.toml
README.md
uv.lock

Установка пакетов

Установка пакетов производится через команду add:

uv add requests

Если нужно установить более одного пакета:

uv add requests yt-dlp

Или если нужна специфичная версия:

uv add requests==2.31.0

Взглянем ещё раз на значение dependences в файле pyproject.toml после установки requests:

[project]
name = "venv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "requests>=2.32.3",
]

Если нужно установить список пакетов с версиями, заносите его в dependenciesи затем выполняете:

uv sync

Отображение дерева зависимостей:

uv tree

Если нужна установка dev зависимостей:

uv add --dev mypy black

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

Чтобы узнать для каких пакетов доступны обновления, для tree доступен флаг outdated:

uv tree --outdated

Обновить пакет можно так:

uv add yt-dlp --upgrade

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

uv sync --upgrade

Если нужна определённая версия:

uv add requests==2.31.0 --upgrade

Если вы установили определённую версию пакета, и в последствии решили обновить её до последней актуальной, то в pyproject.toml, на примере requests, нужно изменить requests==2.31.0 на requests>=2.31.0 и затем уже запустить uv add requests --upgrade.

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

Удалять пакеты можно по одному или сразу несколько:

uv remove requests yt-dlp

Как работать с разными версиями Python в одном проекте

Устанавливаем python 3.10 в дополнение к используемому 3.13, и проверяем количество установленных версий:

uv python install 3.10
uv python list --only-installed

Чтобы у нас появилась возможность использовать 3.10 в окружении, меняем в pyproject.toml requires-python с 3.13 на 3.9:

[project]
name = "venv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.32.3",
]

Если нужно, чтобы версия 3.10 была в окружении по умолчанию:

uv python pin 3.10

Инлайн-запуск нужной версии python, без изменения версии по умолчанию:

uv run --python 3.10 main.py

Если необходимо установить сразу несколько версий python:

uv python install 3.10 3.11 3.12

Можно установить версию python в заданных границах:

uv python install '>=3.8,<3.10'

One more thing

Помимо удобного интерфейса, быстрой скорости работы, инлайн-запуска и возможности работы с несколькими версиями Python в одном окружении, в uv есть мощный инструмент — tool.

Как это работает:

uvx black main.py

Команда uvx black main.py выполняет следующие действия:

uvx создает временное изолированное виртуальное окружение
Загружает и устанавливает пакет black (форматтер кода для Python) в это временное окружение
Запускает инструмент black из установленного пакета
Запущенный black анализирует и форматирует код в файле main.py

Если кратко, то uvx загружает и устанавливает в изолированное окружение пакет, и затем запускает его. Временное изолированное виртуальное окружение находится за пределами нашего окружения venv, в директории cache. Для того, чтобы очистить место временного пребывания пакетов, загружаемых через uvx, достаточно одной команды:

uv cache clean

Кстати, uvx это алиас для uv tool run, призванный упростить ввод, чтобы каждый раз не писать uv tool run.

Рассмотрим наглядный пример:

uvx cowsay -t "Hello Habr"

uvx загрузил и установил пакет cowsay во временное окружение, а затем запустил его. Пакет cowsay генерирует ASCII-арт изображение говорящей или думающей зверушки с текстом, который вы задаете.

Дополнительно, uvx позволяет устанавливать пакеты обычным способом. В отличие от временных установок, пакеты, установленные обычным способом, сохраняются после очистки кэша. Подробнее — тут: Tools uv

В завершение, стоит отметить, что в uv существует более одного способа взаимодействия с инструментом, и это может сбивать с толку, особенно если вы уже встречали другие описания интерфейса. Здесь uv add requests и uv tree, а где то в другой статье uv pip install requests и uv pip list. Вот, что об этом написано в документации (ниже вольная интерпретация):

Интерфейс pip в uv — это скорее эмуляция или низкоуровневая имитация поведения pip, созданная для того, чтобы обеспечить плавный переход для разработчиков, переходящих с pip. Однако, это не тот же pip, который используется в стандартной экосистеме Python. Команды, использующие этот интерфейс, скорее всего, могут отличаться от стандартного поведения pip, и если вы используете эти команды, будьте готовы к возможным отличиям, особенно в нестандартных сценариях. Основная цель этого интерфейса — облегчить переход на uv для тех, кто уже знаком с pip, но для более гибких и сложных операций лучше использовать стандартные команды uv.