Как настроить быстрый и воспроизводимый Python-проект с помощью uv

Когда вы направляете ИИ-агента для написания кода вроде Claude Code или Codex на Python-проект, половина трудностей не имеет отношения к модели. Они идут от окружения: отсутствующие пакеты, не та версия Python, виртуальное окружение, которое агент забыл активировать, или коллега, у которого «на моей машине всё работает». Решение — проект, который воспроизводим по умолчанию, а самый быстрый способ получить такой сегодня — uv, Python-инструментарий на Rust от Astral.

uv заменяет pip, venv, pip-tools и pyenv одной быстрой командой и записывает lock-файл, так что одно и то же дерево зависимостей устанавливается везде. Это руководство проведёт вас от пустого места до зафиксированного, запускаемого проекта за несколько минут.

Почему окружение важно для агента

ИИ-агент выполняет команды в вашей оболочке и читает возвращающиеся ошибки. Если в вашем проекте нет объявленных зависимостей и закреплённой версии Python, агенту приходится угадывать — а неверная догадка отправляет его в кроличью нору установки пакетов глобально или редактирования не того интерпретатора. Проект с pyproject.toml и uv.lock даёт агенту единый источник истины: он может выполнить uv sync, получить нужные пакеты и двигаться дальше. Время на проверку вы тратите на логику, а не на археологию окружения.

Установка uv

На macOS или Linux:

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

На Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv — это единый самодостаточный бинарник, поэтому настраивать больше нечего.

Создание проекта одной командой

uv init weather-cli
cd weather-cli

Это создаёт рабочий проект: pyproject.toml для метаданных и зависимостей, файл .python-version, стартовый main.py, README.md и .gitignore. Вам не нужно создавать или активировать виртуальное окружение вручную — uv управляет .venv за вас в тот момент, когда оно понадобится.

Добавление зависимостей (и почему важен lock-файл)

uv add requests

Это делает сразу три вещи: записывает requests в pyproject.toml, разрешает полное дерево зависимостей и записывает uv.lock с точными, кросс-платформенными закреплёнными версиями. Закрепить версию можно прямо при добавлении:

uv add 'requests==2.31.0'

Закоммитьте uv.lock в Git. Это разница между «установить последний requests» (который со временем дрейфует) и «установить именно то дерево, которое мы протестировали». Когда ваш агент — или ваш CI, или новый коллега — выполняет uv sync, все получают побайтово идентичное окружение.

Запуск кода без активации чего-либо

uv run main.py

uv run следит за тем, чтобы окружение было синхронизировано, и затем выполняет код внутри него — без танцев с source .venv/bin/activate. Для агентов это особенно важно: каждый вызов инструмента часто происходит в новой оболочке, поэтому «активировать, затем запустить» нередко ломается, тогда как один uv run всегда работает. Обернуть можно любую команду:

uv run -- pytest -q
uv run -- flask run -p 3000

Закрепите версию Python, чтобы агент и CI совпадали

uv python pin 3.12

Это записывает версию в .python-version, и uv автоматически скачает и будет использовать этот интерпретатор — системный Python не требуется. Теперь версия, под которую вы разрабатываете, — это версия, которую используют ваш агент, ваши коллеги и ваш CI.

Короткий разобранный пример

Предположим, вы просите агента «добавить команду, которая получает сегодняшнюю погоду». Когда на месте uv, весь цикл получается чистым:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# агент редактирует main.py, чтобы обратиться к API...
uv run main.py

Агенту никогда не приходится рассуждать о том, какой интерпретатор активен или установлен ли requests, — эти факты объявлены в файлах, которые он может прочитать. Если он вводит новую зависимость, он выполняет uv add, и lock-файл обновляется. Если что-то ломается в CI, uv sync воспроизводит точно такое же окружение локально, чтобы вы могли это отладить.

Куда движется uv

uv и родственные ему инструменты ruff (линтер/форматтер) и ty (проверка типов) широко распространены — один только uv скачивают более 100 миллионов раз в месяц. В марте 2026 года OpenAI согласилась приобрести Astral, компанию, стоящую за ними, чтобы интегрировать этот инструментарий в свою платформу Codex, при этом пообещав сохранить инструменты с лицензией MIT в открытом доступе (OpenAI, Simon Willison). На данный момент практический вывод неизменен: uv — самый быстрый путь к Python-проекту, на котором ваш ИИ-агент может строить, не угадывая.

Краткая шпаргалка

Задача	Команда
Создать проект	uv init <name>
Добавить зависимость	uv add <package>
Закрепить Python	uv python pin 3.12
Запустить код	uv run <file or command>
Воспроизвести окружение	uv sync
Обновить lock-файл	uv lock --upgrade-package <pkg>