📁 Проект, зависимости и uv
У любого Python-сервиса на работе есть три файла рядом с кодом: pyproject.toml описывает проект и диапазоны зависимостей, uv.lock фиксирует точные версии всего дерева, а .venv хранит установленные пакеты отдельно от системного Python. Выпадет одно звено — и у коллеги и в проде окажутся другие версии библиотек, а с ними баг «у меня работает». На собеседовании спрашивают, зачем виртуальное окружение, чем lock-файл отличается от requirements.txt, почему uv, а не poetry, и как разложить сервис на FastAPI по слоям
🧠 Как это устроено
pyproject.toml как центр проекта
setup.py, setup.cfg, requirements-dev.txt, .flake8 и .isort.cfg сейчас заменяет один pyproject.toml:
[project]по PEP 621 — имя, версия,requires-pythonиdependencies. Этот раздел читают все современные инструменты: uv, poetry 2, pip, hatch[build-system]— чем собирать пакет.uv init --packageставит свой бэкендuv_build[dependency-groups]по PEP 735 — зависимости для разработки: pytest, ruff, mypy. В собранный пакет они не попадают[tool.*]— настройки инструментов:[tool.ruff],[tool.mypy],[tool.pytest.ini_options]
requires-python ограничивает резолвер. uv подбирает зависимости так, чтобы они подходили ко всем версиям из диапазона: при >=3.11 он не возьмёт версию библиотеки, которой нужен 3.12. Конкретную версию для локальной разработки задаёт файл .python-version
В uv группа dev особенная: uv add --dev pytest пишет её в [dependency-groups], и uv sync с uv run ставят её по умолчанию. --dev, --no-dev и --only-dev — сокращения для --group dev и соседей. Другие группы заводят явно: uv add --group lint ruff. Старое поле tool.uv.dev-dependencies ещё работает, но документация uv обещает его убрать
Что на самом деле лежит в .venv
Виртуальное окружение — каталог со своим site-packages и ссылкой на интерпретатор, который уже стоит в системе. Копии Python там нет. Вот что создал uv для проекта из примера ниже:
.venv/
├── pyvenv.cfg
├── bin/
│ ├── python -> /opt/homebrew/opt/python@3.13/bin/python3.13
│ ├── python3 -> python
│ ├── pytest, ruff, fastapi # скрипты пакетов
│ └── activate, activate.fish, ...
└── lib/python3.13/site-packages/ # fastapi, pydantic, starlette...home = /opt/homebrew/opt/python@3.13/bin
include-system-site-packages = false
version_info = 3.13.5При старте интерпретатор ищет pyvenv.cfg рядом со своим бинарником или уровнем выше. Нашёл — значит, он в окружении: sys.prefix указывает на .venv, а sys.base_prefix на установку, откуда взят интерпретатор. Пути поиска пакетов строятся от sys.prefix, поэтому import fastapi находит пакет из .venv, а не из системы. include-system-site-packages = false отрезает системный site-packages целиком
$ uv run python -c "import sys; print(sys.prefix); print(sys.base_prefix)"
.../orders/.venv
/opt/homebrew/opt/python@3.13/Frameworks/Python.framework/Versions/3.13Отсюда два следствия. Активировать окружение не обязательно: activate только дописывает .venv/bin в начало PATH, а .venv/bin/python app.py работает и без него. И переносить окружение нельзя: в shebang скриптов прописаны абсолютные пути. Его удаляют и создают заново, в git не кладут
Нужно оно потому, что двум сервисам на одной машине бывают нужны несовместимые версии одной библиотеки, а системный Python в Linux-дистрибутиве принадлежит ОС. Как Python ищет модули по sys.path, разобрано на странице про модули, пакеты и импорты
Диапазоны в pyproject и точные версии в lock-файле
В pyproject.toml пишут, с какими версиями проект совместим: fastapi>=0.162.4. Под такой диапазон сегодня подходит одна версия, через месяц другая. К тому же там только прямые зависимости: FastAPI сам тянет starlette, pydantic, anyio и ещё семь пакетов, и их версий в pyproject нет вообще
Lock-файл отвечает на другой вопрос: что именно ставить. В uv.lock записано всё дерево, включая транзитивные зависимости, и для каждого пакета указаны версия, источник, URL файла и его хеш:
[[package]]
name = "starlette"
version = "1.10.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "anyio" },
]
sdist = { url = "https://files.pythonhosted.org/.../starlette-1.10.0.tar.gz", hash = "sha256:b8399098d4c1...", size = 2734356 }
wheels = [
{ url = "https://files.pythonhosted.org/.../starlette-1.10.0-py3-none-any.whl", hash = "sha256:478c0ab3b4ce...", size = 80571 },
]Хеш защищает от подмены: если файл в индексе или зеркале изменился, установка упадёт. uv.lock кроссплатформенный, в нём сразу колёса под Linux, macOS и Windows, поэтому lock, собранный на Mac, ставит те же версии в Linux-контейнере. Lock-файл сервиса коммитят в git. Потребителям библиотеки он не передаётся, им достаются диапазоны из [project]
🛠️ На практике
Проект на uv с нуля
uv от Astral написан на Rust и заменяет pip, pip-tools, pipx, virtualenv, pyenv и poetry одним бинарником. Прогон на uv 0.13.7 и Python 3.13.5, пути сокращены:
uv init --package orders --python 3.13
cd orders
uv add fastapi
uv add --dev pytest ruffCreating virtual environment at: .venv
Resolved 12 packages in 1.09s
Installed 12 packages in 18ms
+ anyio==4.16.0
+ fastapi==0.162.4
+ pydantic==2.14.3
+ pydantic-core==2.50.4
+ starlette==1.10.0
...uv init --package создал src-layout с src/orders/__init__.py, .python-version и git-репозиторий. Первый uv add сам завёл .venv, записал зависимость, построил uv.lock и поставил пакеты. В pyproject после этого:
[project]
name = "orders"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"fastapi>=0.162.4",
]
[dependency-groups]
dev = [
"pytest>=9.2.0",
"ruff>=0.17.4",
]uv пишет нижнюю границу >= на текущую версию, точная живёт в lock-файле. Остальное на каждый день:
| Команда | Что делает |
|---|---|
uv lock | пересобирает uv.lock по pyproject, ничего не ставит |
uv lock --upgrade-package fastapi | поднимает одну зависимость, остальные версии не трогает |
uv sync | приводит .venv в точное соответствие с lock-файлом |
uv run pytest | проверяет lock и окружение, при нужде обновляет их и запускает команду в .venv |
uv export | выгружает lock в requirements.txt с хешами или в pylock.toml по PEP 751 |
uv sync точный по умолчанию: всё, чего нет в lock-файле, он удаляет. Поставил руками uv pip install six — следующий uv sync пишет - six==1.17.0. uv sync --no-dev снёс pytest, ruff и их зависимости, всего 6 пакетов: так ставят в проде
--locked против --frozen
Оба флага не дают uv переписать lock-файл, но проверяют разное. Добавил в pyproject httpx руками и не запустил uv lock:
$ uv sync --locked
Resolved 23 packages in 998ms
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
$ uv sync --frozen
Installed 1 package in 2ms
$ uv run --frozen python -c "import httpx"
ModuleNotFoundError: No module named 'httpx'--locked сверяет lock с pyproject и падает, если они разошлись. --frozen в pyproject не смотрит: ставит записанное в lock и молча пропускает новую зависимость. В CI нужен --locked, он ловит коммит, где поменяли pyproject и забыли lock. --frozen уместен, когда сверка уже прошла на предыдущем шаге. Как uv sync встраивают в Dockerfile, разобрано на странице про Python в контейнере
uvx, uv tool и uv python
uvx ruff check . (полное имя uv tool run) запускает утилиту во временном окружении из кэша uv, не трогая проект. uv tool install ruff ставит её насовсем в отдельное окружение и кладёт бинарник в PATH, как pipx
uv python install 3.13 скачивает сборку CPython из проекта python-build-standalone: официальных переносимых бинарников у Python нет. Заранее ставить не обязательно, недостающую версию uv скачает сам. Это задача pyenv
pip, poetry и uv
| pip + requirements.txt | poetry | uv | |
|---|---|---|---|
| Описание проекта | requirements.txt, часто без pyproject.toml | pyproject.toml, с версии 2.0 в стандартном [project] | pyproject.toml, [project] |
| Lock-файл | нет. Его роль играет pip freeze или pip-compile с хешами | poetry.lock | uv.lock, кроссплатформенный |
| Окружение | создаёшь сам через python -m venv | создаёт сам | создаёт сам в .venv |
| Dev-зависимости | отдельный файл requirements-dev.txt | [tool.poetry.group.*] или PEP 735 | PEP 735, группа dev по умолчанию |
| Версии Python | нет, нужен pyenv | нет, нужен pyenv | uv python install |
| Утилиты вроде ruff | pipx | нет | uvx, uv tool |
| Скорость | базовая | сопоставима с pip | по документации uv в 10–100 раз быстрее pip |
Ruff, pre-commit и mypy в CI
Ruff заменяет flake8 с плагинами, isort, pyupgrade и black: в нём больше 900 правил, а форматтер на больших проектах вроде Django совпадает с black больше чем в 99,9% строк. Правила включают кодами в pyproject:
[tool.ruff]
line-length = 100
[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"] # pycodestyle, pyflakes, isort, bugbear, pyupgradeНа файле с import sys и import os, json, где нужен только json, ruff check нашёл 4 ошибки: I001 (импорты не отсортированы), E401 (два импорта в строке) и два F401 (импорт не используется), и все исправил через --fix. Форматтер импорты не сортирует, это правило линтера I. Поэтому сначала ruff check --fix, потом ruff format
pre-commit запускает то же самое перед каждым коммитом:
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.17.4
hooks:
- id: ruff-check
args: [--fix]
- id: ruff-format # после линтера: фиксы могут сломать форматирование
- repo: https://github.com/astral-sh/uv-pre-commit
rev: 0.13.7
hooks:
- id: uv-lock # пересобирает uv.lock, если поменялся pyprojectХук пропускается через git commit --no-verify, поэтому в CI те же проверки повторяют: uv sync --locked, затем uv run ruff check ., uv run ruff format --check ., uv run mypy src и uv run pytest. ruff format --check ничего не меняет и возвращает код 1, если файл надо переформатировать. Что ловит mypy и как включать strict постепенно, разобрано на странице про аннотации типов и mypy
Структура сервиса: src-layout и слои
Flat layout кладёт пакет в корень репозитория рядом с pyproject.toml, src-layout прячет его в src/. Python ставит текущий каталог первым в путь поиска модулей, поэтому при flat layout import orders из корня берёт исходники напрямую, даже если пакет не установлен или собирается без части файлов. Тесты зелёные, а собранный пакет падает на ModuleNotFoundError. В src-layout импорт работает только после установки, и тесты проверяют то, что поедет в прод. uv ставит проект как editable: в site-packages лежит orders.pth со строкой .../orders/src, и правки видны без переустановки
Цена в том, что без установки проект не запустить: python src/orders/main.py упадёт на импортах, нужен uv run. Flat оправдан для скрипта или учебного проекта
Внутри пакета сервис на FastAPI обычно режут на три слоя:
orders/
├── pyproject.toml
├── uv.lock
├── .python-version
├── src/orders/
│ ├── main.py # create_app: lifespan, middleware, include_router
│ ├── api/
│ │ ├── deps.py # Depends: сессия БД, текущий пользователь
│ │ └── orders.py # роутер: HTTP-запрос → схема → сервис
│ ├── schemas/order.py # Pydantic-модели запросов и ответов
│ ├── services/orders.py # бизнес-правила, транзакция
│ ├── repositories/orders.py # запросы через SQLAlchemy
│ └── models/order.py # ORM-модели
└── tests/- Роутер знает про HTTP: схема запроса, вызов сервиса, статус ответа. Бизнес-логики и SQL в нём нет
- Сервис держит правила вроде «заказ нельзя отменить после отгрузки» и ничего не импортирует из FastAPI, поэтому его зовут и из воркера очереди
- Репозиторий прячет SQL за
get(order_id)иadd(order). Сервис получает его через конструктор, в тесте его легко подменить
# api/orders.py
@router.post("/orders/{order_id}/cancel", response_model=OrderOut)
async def cancel(order_id: int, service: Annotated[OrderService, Depends(get_order_service)]):
try:
return await service.cancel(order_id)
except OrderAlreadyShipped:
raise HTTPException(status.HTTP_409_CONFLICT, "Заказ уже отгружен")
# services/orders.py
class OrderService:
def __init__(self, repo: OrderRepository) -> None:
self.repo = repo
async def cancel(self, order_id: int) -> Order:
order = await self.repo.get(order_id)
if order.status == "shipped":
raise OrderAlreadyShipped(order_id)
order.status = "cancelled"
return orderРаскладка по слоям хороша, пока фич немного. Когда их десяток, режут по доменам: orders/router.py, orders/service.py, orders/repository.py, рядом payments/. Сборка зависимостей через Depends разобрана на странице про FastAPI, сессии и транзакции на странице про SQLAlchemy
⚠️ Где ошибаются
Не коммитят lock-файл. В проде ставятся версии, свежие на день сборки. Выходит минорный релиз транзитивной зависимости с другим поведением, и сервис ломается без единой строки нового кода
Ставят в CI с --frozen вместо --locked. Забытый uv lock после правки pyproject не ловится: сборка зелёная, а новой зависимости в образе нет, и сервис падает на импорте уже после деплоя
Ставят пакеты в системный Python. sudo pip install в Linux перезаписывает пакеты, от которых зависят утилиты ОС, поэтому свежие Debian и Ubuntu отвечают externally-managed-environment и не ставят. Нужно окружение, а для утилит uv tool install
Кладут .venv в git или копируют между машинами. В окружении абсолютные пути и колёса под конкретную ОС и архитектуру, скопированное с Mac на Linux оно не заработает. Переносят lock-файл, окружение пересоздают через uv sync
Бизнес-логика в роутере. SQL и проверки прямо в эндпоинте работают, пока ту же операцию не понадобится вызвать из консьюмера Kafka или крона. Логику копируют, и копии расходятся
🎯 Вопросы с собеседований
Зачем виртуальное окружение и как оно устроено
Чтобы у каждого проекта был свой набор пакетов, не конфликтующий с другими проектами и с системным Python, который нужен ОС. Внутри это каталог с pyvenv.cfg, ссылкой на базовый интерпретатор в bin/ и своим site-packages. Интерпретатор при старте находит pyvenv.cfg рядом с собой и ставит sys.prefix на окружение, а sys.base_prefix оставляет на базовой установке, и пакеты ищутся от sys.prefix. Активация только меняет PATH. Переносить окружение нельзя, в нём абсолютные пути
requirements.txt против pyproject.toml и lock-файла
pyproject.toml описывает проект и диапазоны прямых зависимостей, с которыми он совместим: это стандарт PEP 621, его читают все современные инструменты. Lock-файл фиксирует точные версии всего дерева, включая транзитивные, с хешами файлов, и отвечает на вопрос «что именно ставить». requirements.txt — формат pip, в нём бывает что угодно: от списка диапазонов до полной заморозки с хешами из pip-compile, а после pip freeze там смешаны прямые, транзитивные и случайные пакеты. Сейчас его чаще генерируют из lock-файла через uv export для систем, которые понимают только pip
uv или poetry: чем отличаются
Оба ведут проект через pyproject.toml, сами создают окружение и пишут lock-файл, а poetry с версии 2.0 тоже пишет зависимости в стандартный [project]. Разница в скорости и охвате: uv написан на Rust, ставит пакеты параллельно из глобального кэша и заодно заменяет pyenv (uv python install) и pipx (uvx). У poetry зрелее публикация пакетов и экосистема плагинов
Как зафиксировать версии, чтобы в проде стояло то же, что у тебя локально
Коммитить lock-файл и ставить строго из него: uv sync --locked --no-dev. --locked упадёт, если lock разошёлся с pyproject, тогда как --frozen молча поставил бы старый набор. --no-dev не потащит в прод pytest и ruff. Версию Python фиксируют в .python-version и в базовом образе. Хеши в lock-файле гарантируют те же файлы, а не только те же номера версий. Обновляют зависимости отдельным коммитом через uv lock --upgrade-package имя с прогоном тестов
Как бы ты структурировал сервис на FastAPI
Три слоя. Роутер отвечает за HTTP: разбирает запрос в Pydantic-схему, зовёт сервис и превращает результат и доменные исключения в ответ со статусом. Сервис держит бизнес-правила и не знает про FastAPI, поэтому его вызывают из воркера и тестируют без HTTP. Репозиторий прячет SQL за методами вроде get и add, сервис получает его через конструктор, а собирается всё через Depends. Отдельно лежат схемы, ORM-модели и main.py с lifespan. В маленьком сервисе каталоги по слоям, в большом по доменам
Зачем src-layout
Чтобы тесты проверяли установленный пакет, а не исходники из текущего каталога. Python ставит текущую директорию первой в путь поиска, и при flat layout import orders из корня находит код напрямую, даже если пакет собирается без части файлов: тесты проходят, а в проде ModuleNotFoundError. В src-layout импорт работает только после установки, и лишние файлы корня в путь не попадают. Цена в том, что без установки проект не запустить, но uv и так ставит его как editable
📚 Что почитать
- Документация uv — проекты, lock и sync, группы зависимостей, утилиты и версии Python
- Locking and syncing — разница
--lockedи--frozen, точная синхронизация, частичная установка - venv в документации Python —
pyvenv.cfg,sys.prefixи почему окружение не переносят - src layout vs flat layout — аргументы за и против src-layout от PyPA