uv объединяет создание проекта, выбор Python, зависимости, lock-файл и запуск команд в одном инструменте. Вместо ручного python -m venv, активации окружения и редактирования requirements.txt мы выполним init, add и run. Проектное окружение никуда не исчезнет, просто uv будет поддерживать его сам.
Новичок часто воспринимает виртуальное окружение как отдельный ритуал: создать папку, активировать её, проверить pip, установить пакет, сохранить requirements и не забыть повторить всё на другом компьютере. uv меняет рабочий процесс. Проект описывает зависимости в pyproject.toml, точное разрешение фиксируется в uv.lock, а команда uv run перед запуском убеждается, что окружение синхронизировано. Это не отменяет понимание изоляции. Наоборот, файлы становятся заметнее, а случайный глобальный pip перестаёт влиять на результат.
uv init создаёт структуру проекта и pyproject.toml.
uv add записывает зависимость и обновляет lock-файл.
uv run синхронизирует окружение проекта и выполняет команду в нём.
Какие файлы появляются в uv-проекте
После uv init study-timer появится каталог проекта. pyproject.toml содержит имя, версию Python и прямые зависимости. Файл python-version фиксирует выбранную линию, если шаблон его создаёт. После uv add rich появятся uv.lock и venv-каталог. Lock хранит точное дерево, окружение содержит пакеты конкретной машины. В Git отправляют pyproject.toml и uv.lock, но не локальную среду.
| Файл или каталог | Роль | Добавлять в Git |
|---|---|---|
| pyproject.toml | Метаданные и прямые зависимости | Да |
| uv.lock | Точное разрешение всех пакетов | Да для приложения |
| venv-каталог | Локально установленные файлы среды | Нет |
| main.py | Код учебного приложения | Да |
| .python-version | Предпочитаемая версия Python | Обычно да |
requirements.txt не является обязательным центром нового uv-проекта, но его можно экспортировать для старой системы. Главный источник намерения находится в pyproject.toml, а воспроизводимое решение закрепляет uv.lock.
Четыре команды вместо ручной рутины. Файлы проекта управляют локальной средой
Создаём проект и добавляем первую библиотеку
Установите uv способом из официальной документации и проверьте uv --version. Команды ниже создают небольшое приложение, добавляют Rich, запускают Python внутри проекта и показывают дерево зависимостей. На Windows, macOS и Linux команды uv одинаковы, меняется только способ установки самого бинарного файла. Не копируйте установочную команду вслепую: скачиваемый скрипт можно сначала открыть и проверить.
uv init study-timer
cd study-timer
uv add rich
uv run python -c "from rich import print; print('[bold cyan]uv работает[/bold cyan]')"
uv tree
uv run python -c "import sys; print(sys.executable)"
# После клонирования проекта на другой компьютер:
uv sync
uv run python main.py- uv add rich записывает Rich в pyproject.toml и создаёт точный uv.lock.
- uv run использует интерпретатор из проектного окружения без ручной активации.
- uv tree показывает Rich и его транзитивные зависимости.
- После удаления локальной среды uv sync восстанавливает её по файлам проекта.
Понятия те же, действий меньше. Окружение остаётся изолированным в обоих случаях
Что uv делает во время add и run
uv add меняет декларацию зависимостей, решает совместимые версии и обновляет lock. Затем локальная среда синхронизируется. uv run проверяет, соответствует ли окружение проекту. Другой разработчик получает pyproject.toml и uv.lock, а uv sync создаёт то же дерево для его платформы. Lock не редактируют вручную. Прямую зависимость удаляют через uv remove.
| Привычная задача | Ручной путь | Путь uv |
|---|---|---|
| Создать проект | mkdir и файлы вручную | uv init |
| Создать окружение | python -m venv project-env | Автоматически при sync или run |
| Добавить пакет | pip install и правка списка | uv add rich |
| Запустить код | Активировать venv и python | uv run python main.py |
| Восстановить среду | Создать venv и pip install | uv sync |
| Посмотреть дерево | Дополнительный инструмент | uv tree |
uv init имеет шаблоны приложения и библиотеки. Для первого скрипта подходит приложение. Не смешивайте uv add с произвольным pip install в той же среде: пакет может не попасть в pyproject и lock. Если старый сервис требует requirements.txt, экспортируйте его из lock. uv развивается быстро, поэтому читайте help и актуальные docs.
Проверяем воспроизводимость на чистом окружении
Создайте два проекта. В первом добавьте Rich, во втором Requests. Импортируйте чужую библиотеку через uv run и проверьте изоляцию. Затем удалите только локальную среду study-timer, не трогая pyproject.toml и uv.lock, и запустите uv sync. После восстановления добавьте зависимость, выполните uv remove и сравните файлы.
- Проверьте версию uv и создайте study-timer через uv init.
- Откройте pyproject.toml до добавления пакетов и зафиксируйте dependencies.
- Выполните uv add rich, затем сравните pyproject и uv.lock.
- Запустите sys.executable через uv run и найдите путь проектной среды.
- Удалите только тестовое окружение и восстановите его командой uv sync.
- Создайте второй проект и убедитесь, что его пакеты не видны в первом.
- Вы различаете прямые зависимости, lock-файл и установленное окружение.
- Проект запускается без ручной активации окружения.
- Чистая среда восстанавливается по pyproject и uv.lock.
- Случайный глобальный пакет не маскирует отсутствие зависимости.
Каждый отвечает на свой вопрос. Не подменяйте один слой другим
Переходим с ручного pip без потери понимания
Когда базовый цикл понятен, добавьте группы разработческих зависимостей, запуск тестов и форматтера через uv run. Для однофайлового эксперимента изучите inline metadata и uv run script.py, а для команды, которую не нужно добавлять в проект, используйте uvx. В командной работе зафиксируйте минимальную версию Python, отправляйте lock вместе с приложением и проверяйте изменения lock в code review. Не превращайте uv в ещё один набор магических команд. Его преимущество раскрывается, когда вы можете по файлам объяснить, что должно быть установлено, что установлено сейчас и как воспроизвести среду.
Как изучить тему в Кодике
В Кодике сначала разберите импорт, модули и виртуальные окружения. Затем создайте один и тот же мини-проект старым способом и через uv. Сравнение покажет, какую рутину инструмент забрал, а какие понятия остались: интерпретатор, изоляция, зависимость, версия и точка запуска.
| Шаг | Что изучить | Контрольный вопрос |
|---|---|---|
| 1 | Модули и import | Откуда Python берёт пакет |
| 2 | Виртуальные окружения | Зачем проекту своя среда |
| 3 | pyproject.toml | Где записана прямая зависимость |
| 4 | uv.lock | Чем намерение отличается от решения |
| 5 | uv run и sync | Как восстановить чистый проект |
В Кодике исправьте отсутствующий модуль через обычный venv, затем через uv add и uv run. Нарисуйте три слоя: pyproject, lock и локальная среда. Если вы объясняете их без команды, инструмент помогает, а не скрывает Python.
uv создаёт и синхронизирует окружение, просто активация обычно не нужна.
Локальная среда расходится с файлами проекта. Добавляйте зависимость через uv.
В Git нужны декларация, lock и код, а окружение восстанавливается.
Сначала прочитайте конфликт и поймите ограничение версий. Lock является полезным артефактом.
Что получится в итоге
Проект запускается одной командой, зависимости описаны в pyproject.toml, точное решение хранится в uv.lock, а среда восстанавливается автоматически.
Исчезает ли виртуальное окружение при использовании uv?
Нет. uv создаёт и поддерживает среду, но uv run обычно избавляет от ручной активации.
Чем pyproject.toml отличается от uv.lock?
pyproject описывает прямые требования проекта, а lock фиксирует точное совместимое дерево пакетов.
Нужно ли отправлять venv в Git?
Нет. Среду восстанавливают через uv sync по файлам проекта.
Как понять, что проект действительно работает?
Проверьте основной сценарий, ошибочный ввод, повторный запуск и один граничный случай. Затем объясните вслух, где появляются данные, кто принимает решение и где хранится состояние.
Можно ли начать с готового кода из статьи?
Да. После первого запуска измените один параметр, добавьте одну проверку и повторите проект без подсказки. Так пример превращается в собственный навык.
Импорты и пакеты закрепите в курсе Python. Если окружения пока путают, прочитайте зачем нужен venv и как исправлять No module named.
Современный набор инструментов сравните со статьёй про инструменты Python-разработчика. В Кодике создайте два изолированных проекта и восстановите один из них только по pyproject и lock.