Настройка uv для editable dev-зависимости из локального пути

Для настройки uv python с editable зависимостью из локального пути в группе dev используйте команду uv add --dev --editable ../путь/к/пакету. Это добавит пакет в [dependency-groups.dev] pyproject.toml и создаст [tool.uv.sources] с editable = true, чтобы при uv run --dev или uv sync --dev локальная версия переопределяла основную из [project.dependencies]. Такой трюк идеален для uv dev dependencies, когда нужно тестировать изменения на лету без постоянной публикации.

Содержание

• Что такое uv python и зачем нужны dev-зависимости
• Установка uv python и базовая настройка проекта
• Как добавить editable зависимость в группу dev с uv add
• Переопределение зависимостей при uv run --dev и uv sync
• Настройки pyproject.toml: [tool.uv.sources] и приоритеты групп
• Распространенные проблемы и сравнение с pip/poetry
• Источники
• Заключение

Что такое uv python и зачем нужны dev-зависимости

uv python — это сверхбыстрый менеджер пакетов и проектов на Rust от Astral, который заменяет pip, poetry и venv одним махом. Он решает классические боли: медленная установка, конфликты версий, хаос с виртуальными окружениями. А uv dev dependencies? Это когда вам нужны инструменты только для разработки — тесты, линтеры, форматировщики вроде pytest или ruff. Зачем их отделять?

Потому что в продакшене они не нужны, а в dev — must-have. Представьте: основной список [project.dependencies] содержит стабильные библиотеки вроде requests==2.31.0, а в dev — свежий форк из локальной папки по соседству. Без правильной настройки uv run --dev your-script.py потянет старую версию, и ба-бах — ваши изменения игнорируются. Официальная документация uv подчеркивает: группы вроде dev имеют приоритет, но editable пути требуют явной конфигурации.

Коротко: uv ускоряет всё в 10–100 раз по сравнению с pip. Но фишка в гибкости — один инструмент для всего цикла.

Установка uv python и базовая настройка проекта

Сначала установите uv python. Просто:

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

Или через pipx: pipx install uv. Готово? Проверьте uv --version — увидите что-то вроде 0.4.x (на 2026 год актуально 0.5+).

Теперь создайте проект:

uv init myproject
cd myproject
uv sync

Это сгенерит pyproject.toml с [project] и виртуальным .venv. Добавьте базовые зависимости: uv add requests httpx. Хотите uv dev dependencies? Пока не торопитесь — сначала поймём editable.

Почему uv лучше poetry? Нет ненужных lock-файлов по умолчанию, sync в секундах. Но если мигрируете, uv init --from poetry поможет. А python uv install? Это для глобальной установки пакетов, но для проектов — всегда через add/sync.

Как добавить editable зависимость в группу dev с uv add

Вот сердце вашего вопроса. Допустим, у вас пакет my-local-lib в ../my-local-lib/, и вы хотите его в dev.

Команда-волшебник:

uv add --dev --editable ../my-local-lib

Что происходит? uv парсит setup.py/pyproject.toml локального пакета, добавляет в [dependency-groups.dev] строку вроде my-local-lib = "*" и создаёт:

[tool.uv.sources.my-local-lib]
path = "../my-local-lib"
editable = true

Готово! Локальные изменения теперь видны сразу. Без --editable будет копировать исходники — медленно и бесполезно для dev.

Пример полного pyproject.toml после:

[project]
dependencies = [
 "requests==2.31.0",
]

[dependency-groups]
dev = [
 "pytest",
 "my-local-lib",
]

[tool.uv.sources.my-local-lib]
path = "../my-local-lib"
editable = true

Тестируйте: uv sync --dev. Окружение обновится за миг.

А если пакет уже в основном dependencies? Не паникуйте — dev приоритетнее.

Переопределение зависимостей при uv run --dev и uv sync

Ключевой момент: переопределение. Запустите uv run --dev your-script.py — uv подставит editable my-local-lib вместо версии из [project.dependencies]. Почему? Группы dev активируются флагом --dev, и [tool.uv.sources] глобальны по имени пакета.

Пример сценария:

1. В [project.dependencies]: my-local-lib = "^1.0.0" (из PyPI).
2. В dev: editable из пути.
3. uv run --dev → берёт editable.
4. uv run (без --dev) → PyPI версия.
5. uv sync --dev → uv sync обновит .venv с dev + editable.

uv sync без флагов — только runtime deps. С --dev — полный набор. Идеально для CI/CD: uv sync --frozen --no-dev для продакшена.

Но вопрос: а если конфликты? uv ругается и предлагает resolve. Лучше, чем pip hell.

Настройки pyproject.toml: [tool.uv.sources] и приоритеты групп

Ручная настройка? Редактируйте pyproject.toml напрямую:

[tool.uv.sources]
my-local-lib = { path = "../my-local-lib", editable = true }

[dependency-groups.dev]
my-local-lib = "*"

Приоритеты: dev > optional > main. Документация по настройкам uv рекомендует dependency-groups.dev вместо устаревшего [tool.uv.dev-dependencies].

Ещё трюки:

• Git-репо: uv add --dev git+https://github.com/user/repo.git
• Версия: uv add --dev my-local-lib@==2.0.0
• Workspace: в монорепах sources наследуются.

uv python умнее pip: sources работают как overrides, не дублируя.

Распространенные проблемы и сравнение с pip/poetry

Проблемы? Часто sources глобальны — editable dev перезапишет prod. Обсуждение в GitHub uv подтверждает: для разных версий (dev editable, prod git) используйте --no-dev в билдах.

С pip editable (pip install -e .) — медленно, нет групп. Poetry? poetry add --group dev --path, но sync в минуты, не секунды. uv выигрывает: migrate from poetry to uv — uv init --poetry.

Ошибки:

• “Source not found”? Проверьте путь.
• Конфликты? uv lock --refresh.
• Windows? Пути с / работают.

uv pip-совместим: uv pip install, но для проектов — native команды.

Источники

1. uv Projects Dependencies — Концепции зависимостей, dependency-groups и editable установок: https://docs.astral.sh/uv/concepts/projects/dependencies/
2. uv Settings Reference — Настройки pyproject.toml, приоритеты dev-зависимостей: https://docs.astral.sh/uv/reference/settings/
3. uv GitHub Issue #9537 — Обсуждение переопределения sources в dev-группах и ограничений: https://github.com/astral-sh/uv/issues/9537

Заключение

uv python радикально упрощает жизнь: uv add --dev --editable + uv run --dev — и ваша локальная зависимость правит балом над основной. Главное — sources в pyproject.toml и флаги при sync/run. Забудьте pip/poetry-хаос, переходите на uv для скорости и предсказуемости. Если застряли — документация и issues спасут. Удачи в разработке!