# uv — быстрый менеджер пакетов Python

Индекс LLMS: [llms.txt](/llms.txt)

---

## Что такое uv

`uv` — менеджер пакетов Python, написанный на Rust. Решает одну проблему: стандартный `pip` медленно разрешает зависимости, а `poetry` добавляет свою модель проектов поверх PEP 621. `uv` работает поверх `pyproject.toml`, совместим с PEP 621 и PEP 508, и делает это в разы быстрее.

Под капотом — кэширующий резолвер на Rust, который переиспользует данные из pip-совместимых индексов (PyPI по умолчанию). `uv` может заменить `pip`, `pip-tools`, `virtualenv` и `poetry` в одном инструменте.

> [!NOTE]
> `uv` не требует установленного Python для установки самого себя, но для работы с проектами Python — нужен интерпретатор. `uv` умеет находить и управлять CPython через `uv python`.

## Установка

Самый быстрый путь — curl-скрипт:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Это кладёт бинарник в `~/.local/bin`. Для системы без curl:

```bash
pip install uv
```

Или скачать standalone-бинарник с [GitHub releases](https://github.com/astral-sh/uv/releases).

После установки проверяем версию:

```bash
uv --version
```

> [!WARNING]
> Если `uv` не найден после установки — убедитесь, что `~/.local/bin` в `$PATH`. В Debian/Ubuntu пакет ставится в `/usr/local/bin` при установке через pip.

## Основные команды

Цикл работы с проектом:

```bash
uv init myproject          # создаёт pyproject.toml с PEP 621-метаданными
cd myproject
uv add requests            # добавляет зависимость и обновляет uv.lock
uv add --group dev pytest  # добавляет зависимость в именованную группу
uv sync                    # синхронизирует окружение с lock-файлом
uv run pytest              # запускает команду в .venv проекта
```

Ключевые флаги для повседневной работы:

| Флаг | Что делает |
|---|---|
| `--system` | Устанавливает пакет в системный Python, минуя venv |
| `--no-dev` | Не включает dev-зависимости при синхронизации |
| `--group <name>` | Указывает именованную группу зависимостей |
| `--python <version>` | Выбирает конкретную версию интерпретатора |
| `--locked` | Использует lock-файл без перерезолва |
| `--quiet` | Минимальный вывод |
| `--verbose` | Подробный вывод для дебага |

Управление интерпретаторами:

```bash
uv python list             # показывает найденные CPython
uv python install 3.12     # скачивает и кэширует CPython 3.12
uv python find             # показывает путь к используемому Python
```

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

```bash
uv pip install requests    # аналог pip, но быстрее
uv pip freeze              # вывод установленных пакетов
uv pip uninstall requests  # удаление
```

> [!TIP]
> `uv sync` пересоздаёт `.venv` и устанавливает ровно то, что в `uv.lock`. Это делает его пригодным для CI — результат детерминирован.

## Сравнение с pip и poetry

| Аспект | pip | poetry | uv |
|---|---|---|---|
| Язык реализации | Python | Python + Rust | Rust |
| Модель проектов | setup.py / pyproject.toml | pyproject.toml (свой формат) | pyproject.toml (PEP 621) |
| Скорость резолва | Медленная | Средняя | Быстрая |
| Lock-файл | Нет нативного | poetry.lock | uv.lock |
| Виртуальное окружение | venv / virtualenv | встроенное | встроенное (.venv) |
| Совместимость с pip | Полная | Частичная | Полная |
| Замена pip | — | — | Да |
| Замена poetry | — | — | Да (частично) |

`uv` выигрывает на скорости резолва — в бенчмарках astral-sh он быстрее `pip` в 10–50 раз на крупных dependency graphs. При этом `uv pip` полностью совместим с pip-воркфлоу: `requirements.txt`, `--index-url`, `--find-links`.

> [!WARNING]
> `uv` активно развивается. Формат `uv.lock` может меняться между мажорными версиями. В продакшен-цепочках CI фиксируйте версию `uv` через `uv --version` или установку конкретного бинарника.

Типичная ошибка — путать `uv add` и `uv pip install`. Первый пишет зависимость в `pyproject.toml` и обновляет `uv.lock`, второй работает как pip напрямую. Для проектов с `pyproject.toml` используйте `uv add`. Для одноразовых скриптов и Docker-файтов — `uv pip install`.

Ещё одна частая проблема: `uv` не находит интерпретатор, если Python установлен в нестандартный путь. Решение — `uv python install --force` или явное указание через `--python /path/to/python`.