Edge of Context
Поиск

· Обновлено

[!NOTE] Автоматический перевод Эта статья была автоматически переведена с оригинальной английской версии.

UV на macOS: управление версиями Python, проектами и инструментами

Я перешёл на среду uv в своей работе с Python, поскольку она заменила необходимость постоянно переключаться между инструментами вроде pip, виртуальных сред, pip-tools, pipx и специализированных менеджеров проектов. Теперь один исполняемый файл покрывает большую часть этих задач.

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

Быстрое начало

# Install uv with Homebrew
brew install uv

# Start a project
uv init example-app
cd example-app
uv add httpx
uv run python main.py

# Run an isolated CLI without installing it permanently
uvx ruff check .

# Run a script that declares PEP 723 dependencies
uv run fetch.py

Кратко. Я использую uv add, uv lock, uv sync, и uv run внутри проектов; метаданные согласно PEP 723 для самодостаточных скриптов; uvx для одноразовых инструментов; и uv tool install для команд, которые должны оставаться в активном состоянии PATH. В процессе CI, --locked проверяет соответствие метаданных проекта uv.lock; --frozen доверяет существующему замку, не проверяя его свежесть.

Установка uv с использованием одного владельца

Homebrew представляет собой удобный способ установки на macOS:

brew install uv
uv --version

Если через Homebrew установлен uv, Homebrew должен его обновить:

brew upgrade uv

uv self update Этот параметр предназначен для метода автономной установки UV и отключён при использовании менеджера пакетов. Не допускайте ситуацию, когда два установщика пытаются запустить один и тот же исполняемый файл.

Полезные команды идентификации:

command -v uv
uv python dir
uv tool dir
uv cache dir

Управляемые установки Python, постоянные инструменты и временные записи кэш хранятся в отдельных каталогах. кэш можно удалить и создать заново; он не является единственным источником достоверной информации.

Четыре границы рабочего процесса UV

Проекты: объявления, резолюция и среда

Проект в области UV обычно включает три различных артефакта:

Входные данные и состояние, вычисляемое в проекте uv

Создайте приложение и добавьте рантайм вместе с требованиями к тестированию:

uv init forecast-app
cd forecast-app

uv add httpx
uv add --group test pytest
uv run python main.py
uv run --group test pytest

Текущие шаблоны применения UV создают main.py, pyproject.toml, README.md, и .python-version. По умолчанию они не определяют систему сборки. Используйте uv init --lib для упакованной библиотеки с src настройка макета и сборка бэкенд.

uv run проверяет проект, при необходимости обновляет механизм блокировки, синхронизирует требуемые зависимости и запускает команду. Первая операция над проектом выполняет .venv и uv.lock по мере необходимости; uv init Оно само создаёт только файлы проекта.

Фиксируйте входные данные, а не среду выполнения

Выполнить коммит pyproject.toml, uv.lockисточник, а также целенаправленный .python-version. Игнорировать .venv а также UV-параметры кэши.

Локк фиксирует результат обработки для всех поддерживаемых маркеров и платформ; однако он не делает нативные движки идентичными на macOS, Linux, процессорах Intel и Apple Silicon. Необходимо протестировать каждую платформу деплой.

Защита свежести данных: --locked не является --frozen

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

Использовать --locked чтобы обеспечить согласованность замка с метаданными проекта:

uv lock --check
uv sync --locked
uv run --locked pytest

Если pyproject.toml и uv.lock Не согласен: эти команды приводят к сбоям, вместо того чтобы устанавливать новый лок. Обычно именно это и является полезным этапом проверки в CI.

Использовать --frozen только тогда, когда вы намеренно хотите, чтобы UV использовал существующий замок без проверки его актуальности:

uv sync --frozen

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

Управляемый Python: запрос на конкретную версию, а не универсальный бинарник

uv позволяет загружать и управлять дистрибутивами Python:

uv python install 3.12 3.13
uv python list --only-installed
uv python pin 3.12

управляемые сборки CPython от uv поступают из python-build-standalone Проект uv также способен обнаруживать интерпретаторы системы, Homebrew, pyenv, Conda и другие.

.python-version это запрос на обновление версии, обнаруженный с помощью uv и других совместимых инструментов. requires-python в pyproject.toml это контракт совместимости проекта. Сохраняйте оба варианта без изменений:

[project]
requires-python = ">=3.12,<3.14"

фиксация 3.12

использовать другой менеджер Python, когда проекту требуется конфигурация распространения или сборки, которую uv не предоставляет. uv всё равно может задействовать этот интерпретатор через --python или обычное открытие.

Выберите среди uv run, uvx, а также установленные инструменты

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

Инструменты, связанные с проектом: uv run

Если pytest, mypy, генератор кода или другой инструмент должны импортировать проект или использовать его заблокированные плагины, указайте их в группе зависимостей:

uv add --group lint ruff
uv run --group lint ruff check .

Запуск этого инструмента uvx Это приведёт к изоляции данного компонента от остальной части проекта, а также может скрыть установленные пакеты или плагины, необходимые для его работы.

Инструменты ad hoc: uvx

uvx является псевдонимом для uv tool run. Он создаёт изолированную среду, хранящуюся в временном uv кэш:

uvx ruff@0.12.0 check .
uvx --from jupyterlab jupyter lab
uvx --with mkdocs-material mkdocs --help

Фиксируйте версию инструмента в процессах CI или в документации. При первом запуске без указания версии выбирается текущая релизная версия, а последующие запуски могут повторно использовать состояние кэш.

Перманентные исполняемые файлы: uv tool install

Установите инструмент в тех случаях, когда скрипты, находящиеся вне вашего контроля, требуют выполнения его команды. PATH, или когда манифест машины намеренно присваивает ему владение:

uv tool install 'ruff==0.12.0'
uv tool list
uv tool upgrade ruff
uv tool uninstall ruff

Инструменты с постоянным хранением всё ещё используют изолированные среды. Не вносите изменения в эти среды вручную с помощью pip.

Скрипты: превращение одного файла в единицу релиза

PEP 723 определяет метаданные встроенных скриптов. Совместимый интерпретатор способен считать блок комментариев и создать изолированную среду.

Анатомия скрипта согласно PEP 723

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "httpx>=0.27,<1",
# ]
# ///
import httpx


response = httpx.get("https://example.com", timeout=10)
response.raise_for_status()
print(response.status_code)

Запустите и отредактируйте метаданные с помощью uv:

uv run fetch.py
uv add --script fetch.py rich
uv remove --script fetch.py rich

обычный python fetch.py игнорирует метаданные комментария. Поэтому скрипт требует наличия совместимого запускающего инструмента, несмотря на то, что синтаксис Python остаётся корректным.

Для скрипта, который должен воспроизвести определённое разрешение позже, создайте смежный блокировочный механизм:

uv lock --script fetch.py
uv run --script fetch.py

Этот модуль осуществляет запись. fetch.py.lock. Ан exclude-newer Временная метка может ограничивать диапазон дат распространения кандидатов, однако её влияние слабее, чем у точного фиксированного решения, и она не гарантирует, что артефакт будет оставаться доступным.

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

Файлы требований: совместимость, а не сбои

А requirements.txt Файл может содержать неструктурированные входные данные, точные значения пинов, хэши, ограничения, индексы, URL-адреса или сборку окружения. Воспроизводимость результата зависит от способа его создания и использования; одного только имени файла недостаточно для получения информации.

Используйте интерфейс uv, совместимый с pip, без необходимости миграции:

uv venv
uv pip sync requirements.txt
uv run python app.py

uv pip sync приводит среду в соответствие с содержимым файла, при этом uv pip install -r является аддитивным.

Для собственного приложения поэтапная миграция может оказаться полезной:

uv init --bare
uv add -r requirements.in
uv add --group test -r requirements-test.in
uv lock
uv sync --locked

Запустите полный набор тестов и путь деплой перед удалением старых файлов. Если последующая система по-прежнему ожидает формат pip, сгенерируйте его на основе проверенного файла uv lock:

uv export --format requirements.txt \
  --output-file requirements.txt

Не осуществлять техническое обслуживание uv.lock а также ручно отредактированный экспорт в виде двух конкурирующих разрешений.

Кэш, индексы и границы цепочки поставок

UV кэш способствует ускорению процесса многократной установки, однако остаётся временным решением:

uv cache prune
uv cache clean

Предпочтительно prune для рутинной очистки. clean удаляет все записи кэш и принудительно запускает последующие загрузки и сборки.

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

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

Компактный чек-лист операций

Для каждого проекта:

  1. Определить requires-python и прямые зависимости в pyproject.toml2. Разделяйте опубликованные дополнения от локальных групп зависимостей.
  2. Выполняйте коммит. uv.lock; игнорировать .venv и состояние кэш.
  3. Запустить инструменты, связанные с проектом, внутри среды проекта.
  4. Использовать uv lock --check или --locked в рамках CI-процесса.
  5. Проводить тестирование на каждой целевой ОС и архитектуре, указанных в файле lock.
  6. Экспортировать форматы сведений о совместимости только для определённых конечных пользователей.
  7. Анализировать политику исходного кода и учетных данных независимо от процесса разрешения конфликтов.

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

Список литературы