Установка пакетов с помощью uv в проектах Python

Раздел: Инструменты -> Управление зависимостями

Менеджер пакетов uv создан для ускорения процессов установки зависимостей в Python. Он написан на Rust и предлагает альтернативу традиционному pip. Основная цель uv - обеспечить быстрое разрешение зависимостей и установку пакетов, что особенно полезно в CI/CD pipeline и при работе с большими проектами.

Основной способ установки пакетов: uv pip install

Самый распространенный вариант - использование команды uv pip install. Она повторяет синтаксис pip, но работает быстрее.

uv pip install requests

Installing python modules (установка модулей python)

Как установить конкретную версию пакета?

uv pip install requests==2.28.0

Python requirements (файл requirements.txt в python)

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

Типичная ошибка: при установке из реестра PyPI может возникнуть конфликт зависимостей. uv выводит сообщение "Resolution error: No matching distribution found". Решение - проверить правильность написания имени пакета или использовать флаг --index-url для указания альтернативного реестра.

Целесообразно использовать uv pip install для быстрой установки отдельных библиотек в рамках существующего виртуального окружения.

Как установить пакет из локального файла (wheel или tar.gz)?

uv pip install ./dist/my_package-0.1.0-py3-none-any.whl

Python requirements file (файл requirements.txt в python)

Такой подход применяется для тестирования собранной версии перед публикацией или при использовании пакетов, недоступных в публичных реестрах.

Возможная проблема: если файл поврежден или несовместим с архитектурой (например, *-win_amd64.whl на Linux), uv выдаст ошибку "is not a supported wheel on this platform". Решение - собрать wheel под целевую платформу или использовать исходный код.

Как установить пакет напрямую из git репозитория?

uv pip install git+https://github.com/psf/requests.git@v2.28.0

Python get requirements (получение списка зависимостей requirements.txt в python)

После git+ указывается URL репозитория, опционально с указанием тега, ветки или коммита через @. Это удобно, когда необходимо использовать последние изменения, еще не выпущенные в PyPI.

Ошибка: если репозиторий приватный, потребуется аутентификация. uv не поддерживает автоматический ввод пароля. Решение - использовать URL с токеном: git+https://token@github.com/... или настроить SSH.

Как установить пакет с дополнительными зависимостями (extras)?

uv pip install "pandas[excel]"

сделать requirements python (создание requirements.txt для python)

Extras - это дополнительные опции, которые подключают транзитивные зависимости, например, поддержку Excel в pandas.

Как установить пакет в режиме разработки (editable install)?

uv pip install -e ./my_project

Python uv install (установка пакетов с помощью uv в python)

Ключ -e (editable) устанавливает пакет так, что изменения в исходном коде сразу применяются без переустановки. Используется при активной разработке собственного пакета.

Как установить зависимости из pyproject.toml с помощью uv?

uv pip install -r pyproject.toml

Если файл pyproject.toml содержит секцию [project] с dependencies, uv извлечет все перечисленные пакеты. Однако более эффективно использовать команду uv sync, которая работает быстрее и учитывает секцию [tool.uv].

Проблема: при дублировании требований в нескольких файлах (requirements.txt + pyproject.toml) возможна путаница. Рекомендуется выбрать один источник зависимостей.

Каждый из этих вариантов решает конкретную задачу: локальная установка ускоряет отладку, git - доступ к свежим коммитам, extras - подключает нужные модули без лишних зависимостей.

- No matching distribution found for python (решение ошибки «no matching distribution found» при установке пакетов python)

- Python файл requirements (файл requirements.txt в python)

- как создать requirements txt файл python (создать файл requirements.txt)

Расширенные примеры установки с помощью uv

Ниже приведены команды с дополнительными флагами и сценариями, редко встречающимися в базовых руководствах.

Установка с указанием нескольких индексных серверов

Пример

uv pip install my-package --index-url https://pypi.org/simple --extra-index-url https://private-repo.com/simple

Первый реестр считается основным, второй используется для поиска, если в основном пакет не найден. Полезно для организаций с собственным репозиторием.

Установка без кэширования

Пример

uv pip install --no-cache numpy

Флаг --no-cache отключает использование кэша. Применяется, когда требуется получить самую свежую версию или при проблемах с поврежденным кэшем.

Установка с понижением версии (downgrade)

Пример

uv pip install 'numpy>=1.21,<1.24'

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

Установка только основных зависимостей (без транзитивных)

Пример

uv pip install --no-deps flask

Флаг --no-deps предотвращает установку транзитивных зависимостей. Используется для изолированной проверки самого пакета без его окружения.

Установка в конкретный каталог (target)

Пример

uv pip install --target ./custom_libs requests

Пакеты будут установлены не в site-packages, а в указанную директорию. Применяется при создании zip-приложений или переносимых окружений.

Установка с привязкой к определённому Python интерпретатору

Пример

uv pip install --python python3.11 pandas

Если в системе несколько версий Python, uv установит пакет только для указанного интерпретатора (требуется, чтобы uv был установлен для каждой версии).

Установка из требований с комментариями и флагами

Пример

# Содержимое requirements.txt:
requests
numpy==1.21.0
--extra-index-url https://private.example.com
--trusted-host private.example.com

# Команда:
uv pip install -r requirements.txt

uv поддерживает все флаги pip в файле требований, что позволяет смешивать пакеты и параметры реестра.

Установка с использованием uv sync и lock-файла

Пример

# Создание виртуального окружения
uv venv
# Установка зависимостей из pyproject.toml и блокировка версий
uv sync
# Будет создан файл uv.lock, который гарантирует воспроизводимость

Команда uv sync анализирует pyproject.toml, разрешает зависимости и устанавливает их, параллельно генерируя uv.lock. Это предпочтительный способ для проектов с воспроизводимым окружением.

Пример вывода после успешной синхронизации:

Resolved 42 packages in 0.85s
Installed 42 packages in 0.12s

Время разрешения и установки значительно меньше, чем у pip (на больших проектах разница может составлять 5–10 раз).

Установка в изолированное виртуальное окружение с последующей активацией

Пример

uv venv .venv --python 3.12
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows
uv pip install jupyter

Создается чистое окружение, в которое устанавливается jupyter. Это безопаснее, чем установка в системный Python.

Ошибка при работе с приватными реестрами и способ её обхода

Пример

# Попытка установки из реестра, требующего аутентификации
uv pip install --index-url https://user:pass@private.org/simple mylib
# При неудачной аутентификации uv выдаёт: Error: HTTP 401 Unauthorized
# Решение: использовать переменные окружения
# export UV_INDEX_USERNAME=user
# export UV_INDEX_PASSWORD=pass
uv pip install --index-url https://private.org/simple mylib

Переменные окружения позволяют избежать передачи пароля в истории команд.

Установка пакетов с помощью uv в Python - comments

Python uv install (python)