uv: установка, окружение и воспроизводимый запуск Python-проекта

uv управляет версиями Python, виртуальными окружениями, зависимостями и lock-файлом.
Он особенно удобен в учебном проекте: одна команда восстанавливает окружение, а
uv run запускает программу или тесты с нужными пакетами.

Установка

Официальный установщик для macOS и Linux:

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

Windows PowerShell:

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

Homebrew на macOS:

brew install uv

Закрой и заново открой терминал, затем проверь:

uv --version

Актуальные способы установки всегда перечислены в
официальной документации Astral.

Если команда uv не найдена

Сначала перезапусти терминал и повтори uv --version. Установщик мог изменить
PATH, а уже открытое окно ещё не увидело это изменение.

Если не помогло:

• macOS/Linux: выполни command -v uv;
• Windows PowerShell: выполни Get-Command uv;
• проверь, не завершился ли установщик предупреждением о PATH;
• не запускай команду из Python-консоли с приглашением >>> — нужен терминал.

Не копируй исполняемый файл uv внутрь проекта. Исправь установку или PATH.

Открытие готового проекта

Перейди в каталог, где лежат pyproject.toml и uv.lock:

cd путь/к/проекту
uv sync --frozen

Если проект содержит группу dev с pytest и другими учебными инструментами:

uv sync --frozen --dev

Группа dev обычно включается по умолчанию, но явный --dev делает намерение
понятным. uv sync создаст .venv, если окружения ещё нет.

--frozen означает: использовать существующий uv.lock, не проверяя и не меняя
его. Для строгой проверки, что lock-файл соответствует pyproject.toml, применяется
--locked. В готовом учебном архиве следуй команде из README проекта.

Запуск команд

Активировать .venv вручную не требуется:

uv run python main.py
uv run fastapi dev app/main.py
uv run pytest -q
uv run ruff check .

uv run находит проект, синхронизирует окружение и запускает команду внутри него.
Выполняй её из каталога проекта или его дочерней папки.

Создание нового проекта

uv init my-project
cd my-project
uv add fastapi --extra standard
uv add --dev pytest httpx ruff

Обычные зависимости записываются в [project].dependencies, а инструменты разработки
— в стандартизированную группу:

[dependency-groups]
dev = [
    "httpx>=0.28",
    "pytest>=8",
    "ruff>=0.12",
]

После uv add, uv sync или первого uv run появятся .venv и uv.lock.

Что хранить в Git

Коммить:

• pyproject.toml;
• uv.lock;
• .python-version, если проект фиксирует Python;
• исходный код и тесты.

Не коммить:

• .venv/;
• .env с секретами;
• .pytest_cache/, .ruff_cache/ и __pycache__/.

Минимальный .gitignore:

.venv/
.env
__pycache__/
.pytest_cache/
.ruff_cache/

Частые ошибки

• No pyproject.toml found — перейди в распакованный каталог проекта.
• Lock-файл нельзя изменить с --frozen — не удаляй uv.lock; для осознанного
  обновления зависимостей используй uv lock без --frozen.
• Модуль не найден после sync — запускай через uv run и проверь, что зависимость
  объявлена в pyproject.toml.
• Редактор не видит пакеты — выбери интерпретатор <проект>/.venv/bin/python,
  а на Windows — <проект>\.venv\Scripts\python.exe.
• Случайно изменился uv.lock — проверь git diff uv.lock; не коммить изменение,
  если зависимости менять не требовалось.

Официальная документация

• Проекты uv
• Locking и syncing