Текст и данные · Инструкция
uv tool run или uv tool install что выбрать
Выбирайте `uv tool run`/`uvx`, когда CLI нужен разово или в скрипте без постоянной установки; `uv tool install` подходит для команды, которой вы пользуетесь регулярно из shell. Оба варианта создают изолированное tool-окружение, поэтому это не способ запускать инструмент внутри зависимостей текущего `.venv` проекта.
Короткий ответ
`uv tool run`/`uvx` удобен для разового изолированного запуска, а `uv tool install` — для постоянного CLI, доступного из shell.
Как команда влияет на uvx и Python CLI
`uvx` является алиасом `uv tool run`; инструмент запускается в изолированном от проекта tool-окружении. `uv tool install` создаёт постоянное окружение инструмента и размещает исполняемые файлы в каталоге, который должен быть в `PATH`. Если CLI должен видеть зависимости текущего Python-проекта, документация uv советует рассматривать `uv run`, а не изолированный tool-интерфейс.
Совет: Для CI и одноразовых утилит фиксированная версия в `uvx` обычно важнее удобства latest.
Порядок действий для изолированное окружение
- Шаг 1: Определите, нужен ли инструмент однократно/в CI или как постоянная команда разработчика.
- Шаг 2: Для разового запуска используйте `uvx <tool>` и при необходимости явно закрепляйте версию.
- Шаг 3: Для постоянного CLI используйте `uv tool install <tool>` и проверьте, что каталог executable uv находится в `PATH`.
- Шаг 4: Не модифицируйте tool-окружение вручную через pip; дополнительные зависимости задавайте параметрами uv.
Чек-лист: uv tool run или install: что выбрать для CLI
- Определено, нужен CLI один раз или должен оставаться доступным между сессиями.
- Для воспроизводимого запуска зафиксирована версия инструмента, если latest нежелателен.
- После `uv tool install` исполняемый файл действительно находится через `PATH`.
- Инструмент не ожидает пакеты из проектного `.venv`; если ожидает, выбран `uv run`.
- Повторный запуск использует ожидаемую версию и не требует ручной установки через pip.
Как выбор влияет на версию инструмента и PATH
Для одноразового запуска `uvx` удобен тем, что не требует отдельного шага установки: окружение инструмента создаётся и кэшируется uv. Если важна воспроизводимость, задавайте требуемую версию явно, а не полагайтесь на плавающий latest. `uv tool install` оставляет инструмент установленным до явного удаления и делает его исполняемые файлы доступными через каталог инструментов uv; этот каталог должен быть в `PATH`. Если CLI должен импортировать библиотеки именно из проекта, используйте проектный сценарий `uv run`, иначе изоляция tool-окружения даст другой набор пакетов.
Что пойдёт не так при неверном выборе
Не выбирайте `uv tool run` для инструмента, которому принципиально нужны пакеты именно из `.venv` проекта: изоляция в этом случае работает против вас.
Практический критерий: run или install
Правильный выбор виден по жизненному циклу команды: разовый `uvx` не требует обслуживания постоянной установки, а установленный tool доступен из нового shell без повторного install. Если инструмент неожиданно не видит библиотеки проекта, не добавляйте их вслепую в tool-окружение — сначала проверьте, не должен ли этот сценарий выполняться через `uv run`.
Важно: После постоянной установки проверьте команду из нового shell: текущая сессия может скрывать проблему с `PATH`.
Что учитывать
Не выбирайте `uv tool run` для инструмента, которому принципиально нужны пакеты именно из `.venv` проекта: изоляция в этом случае работает против вас.
Источники и проверка
Фактическая часть сверена по первичным источникам (в т.ч. uv tools). Пример и формулировки — редакция N1RO на 2026-09-23.