- BrainTools - https://www.braintools.ru -
Переезд с pip на uv обычно выглядит как правка трёх строк в Dockerfile. pip install -r requirements.txt превращается в uv sync --locked, рядом появляется COPY --from=ghcr.io/astral-sh/uv, и сборка ускоряется в разы. Lock-файл фиксирует каждую зависимость из индекса вместе с хешем. Вопрос воспроизводимости вроде бы закрыт.
Только pip почти ничего не решал сам. Интерпретатор брался из базового образа, байткод компилировался при установке, а окружение после RUN никто не трогал. uv решает за вас гораздо больше: откуда взять Python [1], когда синхронизировать окружение, что из него удалить, нужен ли .pyc. Решения разумные. Но в Dockerfile, переписанном с pip построчно, каждое из них срабатывает не там, где его ждёшь.
Самое свежее случилось 9 октября. В этот день вышли Python 3.15.0 и uv 0.13.0, и в 0.13.0 версией по умолчанию стала 3.15. Я взял один и тот же pyproject.toml и прогнал его через uv 0.12.24 и 0.13.2. Первый собрал окружение. Второй упал на сборке пакета, который ещё вчера ставился из готового колеса.
Проект самый обычный: requires-python = ">=3.11", одна зависимость pydantic==2.12.5, файла .python-version нет. Системного Python в образе тоже нет — так бывает, когда база это debian:trixie-slim или образ самого uv без интерпретатора. Такой образ я имитировал переменной UV_PYTHON_PREFERENCE=only-managed: с ней uv не видит системный интерпретатор. Запускаем uv lock и uv sync --locked двумя версиями uv:
=== uv 0.12.24
Using CPython 3.14.8
+ pydantic==2.12.5
+ pydantic-core==2.41.5
=== uv 0.13.2
Using CPython 3.15.0
Building pydantic-core==2.41.5
error: Failed to build `pydantic-core==2.41.5`
error: the configured Python interpreter version (3.15) is newer than PyO3's maximum supported version (3.14)
Lock в обоих случаях одинаковый. uv ставит из него pydantic-core==2.41.5. У этой версии есть колёса от cp39 до cp314. Колеса под 3.15 нет: версия вышла в ноябре 2025-го, задолго до 3.15. Раз колеса нет, uv берёт исходники. Собирает их maturin. Сборка дошла до проверки версии в PyO3, и отсутствие Rust её бы не остановило. maturin, не найдя cargo, сам скачивает тулчейн во временный каталог (выключается это переменной MATURIN_NO_INSTALL_RUST=1). В образе без Rust сборка только заметно затянется, прежде чем упасть.
Для uv requires-python = ">=3.11" — это диапазон. Если в системе нет подходящего интерпретатора и нет пина, uv скачивает свою версию по умолчанию. В changelog 0.13.0 смена этой версии стоит первым пунктом в разделе ломающих изменений. Lock к этому решению отношения не имеет. uv строит его универсальным: для каждой версии Python из диапазона и для каждой платформы в нём записано, какие пакеты ставить, а там, где ответы расходятся, lock раздваивается по маркерам вроде python_full_version >= '3.13', так что один и тот же файл годится и для 3.11, и для 3.15, и выбор конкретной версии происходит позже, в момент uv sync. Lock проверяет, что пакеты совместимы с диапазоном по метаданным. Есть ли у них колёса под каждую версию из него, он не проверяет.
Такие нюансы требуют понимания Python чуть глубже привычной работы с кодом. Проверить свои знания на продвинутом уровне можно с помощью вступительного теста [2] — заодно оценить, какие темы стоит подтянуть.
Почему это замечают не все? Если в базовом образе уже есть Python, который подходит под requires-python, uv спокойно берёт его. В python:3.12-slim никакого скачивания не будет, и обновление uv пройдёт незаметно. Ломаются образы без своего интерпретатора и шаги вида RUN uv python install без версии. В гайде по Docker такой шаг есть, и без .python-version он с 9 октября ставит 3.15 даже поверх системного Python. Дальше uv sync берёт уже управляемый 3.15: по умолчанию uv ставит свои интерпретаторы выше системных, как только они установлены. Так что и python:3.12-slim с этим шагом из гайда переезжает на 3.15.
Увидеть выбор uv несложно. В логе сборки uv sync пишет Using CPython 3.15.0 сразу после строк о скачивании интерпретатора, и эту строку стоит хотя бы раз прочитать глазами. Для самопроверки в CI после uv sync хватает .venv/bin/python -V со сравнением с ожидаемой версией. uv python find для этого не годится: до синхронизации в образе без Python он падает с No interpreter found, а после неё печатает путь .venv/bin/python без номера версии.
Чинится всё одной строкой. Её легко забыть закоммитить. uv python pin 3.14 создаёт .python-version, и этот файл надо скопировать в образ до uv sync, иначе uv его не увидит. С самим uv та же история. Гайд советует брать образ с конкретной версией, ghcr.io/astral-sh/uv:0.13.2, а не latest. С latest версия Python по умолчанию меняется вместе с релизом uv, а не тогда, когда вы решите.
Допустим, Python закреплён, uv скачал его в builder-стадии, окружение собралось. Дальше обычная многостадийная сборка: в финальный образ уезжает только /app/.venv, без uv и без кэша. Смотрим, на что указывает Python внутри окружения (каталог установки на стенде задан через UV_PYTHON_INSTALL_DIR=/opt/uvpy):
$ ls -l .venv/bin/python
.venv/bin/python -> /opt/uvpy/cpython-3.13-linux-x86_64-gnu/bin/python3.13
$ .venv/bin/python -c 'print(1)'
bash: .venv/bin/python: No such file or directory
$ .venv/bin/httpx --version
bash: .venv/bin/httpx: cannot execute: required file not found
Виртуальное окружение не содержит самого интерпретатора — в нём только симлинк. Управляемый Python uv по умолчанию кладёт в ~/.local/share/uv/python, а в финальном образе этой папки нет. Ошибка [3] выглядит издевательски: файл .venv/bin/python на месте, ls его показывает, а запустить нельзя. В Docker это превращается в exec /app/.venv/bin/my_app: no such file or directory при старте контейнера.
Кстати, симлинк ведёт не на cpython-3.13.16, а на каталог cpython-3.13-linux-x86_64-gnu без номера патча. Этот псевдоним uv делает нарочно: окружения должны переживать обновление патч-версии через uv python upgrade. На многостадийную сборку он не влияет — живёт там же, где и сам Python.
В официальном примере многостадийной сборки от Astral стоит строка ENV UV_PYTHON_DOWNLOADS=0 с комментарием, что в обеих стадиях используется системный интерпретатор. А у финального FROM в их же репозитории с примерами отдельно сказано, что образ должен совпадать с builder, иначе путь к Python будет другим. Эту строку легко принять за оптимизацию и выкинуть. Без неё uv скачает собственный Python, как только .python-version или requires-python попросят версию, которой нет в базовом образе. Финальный образ получит окружение со ссылкой в пустоту. Если управляемый Python нужен осознанно, его ставят в предсказуемое место и копируют вместе с окружением:
ENV UV_PYTHON_INSTALL_DIR=/python
ENV UV_PYTHON_PREFERENCE=only-managed
WORKDIR /app
COPY .python-version ./
RUN uv python install # версия берётся из .python-version
RUN uv sync --locked --no-dev
# ...
COPY --from=builder /python /python
COPY --from=builder /app/.venv /app/.venv
Путь /python должен совпадать в обеих стадиях до буквы. Симлинк абсолютный, и никакой магии поиска интерпретатора здесь нет.
Следующая поломка случается, когда WORKDIR в стадиях разный. Сборка идёт в /app, а сервис запускается из /srv/app, например потому, что так устроены остальные образы. Python из перенесённого окружения работает нормально, python -c 'import httpx' проходит. А вот любой консольный скрипт из .venv/bin падает:
$ head -1 /srv/app/.venv/bin/httpx
#!/app/.venv/bin/python
$ /srv/app/.venv/bin/httpx --version
bash: /srv/app/.venv/bin/httpx: cannot execute: required file not found
Шебанг у каждого скрипта абсолютный. Записывается он в момент установки, pip делает так же, и поэтому любой скрипт из .venv/bin, будь то сервер приложений, воркер очереди или утилита миграций, после переезда окружения в другой каталог ищет интерпретатор по старому пути, которого в новом образе просто нет. uvicorn, gunicorn, celery, alembic в финальном образе смотрят в /app/.venv/bin/python. Проще всего держать один и тот же путь в обеих стадиях.
Если не получается, окружение создают заранее. Для этого есть uv venv --relocatable. Последующий uv sync ставит пакеты уже в переносимое окружение, и шебанг превращается в маленькую обёртку на /bin/sh, которая ищет Python рядом с собой. Флага --relocatable у самого uv sync нет. Переменная UV_VENV_RELOCATABLE для него тоже ничего не меняет: я проверил, шебанг остаётся абсолютным. Есть ещё preview-режим relocatable-envs-default, с которым uv sync сразу создаёт переносимое окружение, но это пока предварительная функция.
С запуском своя история. В гайде по Docker команда по умолчанию выглядит так: CMD ["uv", "run", "my_app"]. uv run перед запуском проверяет lock и синхронизирует окружение, причём по своим умолчаниям, а не по тем, с которыми собирался образ.
Собираем окружение через uv sync --locked --no-dev, в группе dev у нас pytest и ipython. Потом запускаем приложение через uv run:
$ uv sync --locked --no-dev
$ uv run python -c 'import httpx'
Downloading pygments (1.2MiB)
Downloading jedi (4.7MiB)
Installed 20 packages in 53ms
Флаг --no-dev действует только на ту команду, которой его передали. Никакой памяти [4] о нём в окружении не остаётся: в .venv не записано, с какими группами его собирали, поэтому каждая следующая команда uv решает это заново по своим аргументам и переменным окружения. uv run о нём ничего не знает и доставляет группу dev уже на старте контейнера, со скачиванием из сети. Нет сети — контейнер падает. С корнем только для чтения пакеты ставить некуда. Если всё доступно, контейнер просто стартует дольше и с pytest внутри.
В гайде этой проблемы не видно, потому что там стоит ENV UV_NO_DEV=1. Переменная окружения живёт в образе и действует и на uv sync, и на uv run. Заменив её флагом, вы меняете поведение [5], хотя строка выглядит равносильной.
Та же автоматика срабатывает и с lock-файлом. Добавим в pyproject.toml зависимость, не пересобирая lock, и запустим uv run уже с UV_NO_DEV=1. uv молча обновил uv.lock на 54 строки, поставил новый пакет и только потом запустил приложение. В контейнере это значит запись в файл проекта на старте, а в read-only образе писать её некуда.
uv run синхронизирует неточно: доставляет недостающее, но ничего не удаляет. uv sync, наоборот, по умолчанию точный и удаляет всё, чего нет в lock. Следующий же uv sync --frozen --no-dev в этом окружении снёс доставленные пакеты группы dev. Под ту же точность попадает и привычный по pip шаг RUN uv pip install debugpy где-то посреди Dockerfile:
$ uv pip install debugpy==1.8.17
$ uv sync --locked --no-dev
Uninstalled 1 package in 4ms
- debugpy==1.8.17
Пакета нет в lock — значит, для uv sync он лишний. Если отладчик нужен в образе, ему место в отдельной группе зависимостей, а не в ручной установке. И порядок шагов тут не спасает: любой uv sync после ручной установки сделает то же самое. Для финального образа надёжнее обойтись без uv на старте: ENV PATH="/app/.venv/bin:$PATH" и CMD ["my_app"]. Если uv в образе всё-таки нужен, есть uv run --no-sync и переменная UV_NO_SYNC=1.
Два почти одинаковых флага путают постоянно. --locked требует, чтобы lock соответствовал pyproject.toml, и падает, если это не так. --frozen берёт lock как есть и ничего не проверяет.
Добавим в pyproject.toml зависимость и забудем пересобрать lock:
$ uv sync --frozen --no-dev
$ .venv/bin/python -c 'import orjson'
ModuleNotFoundError: No module named 'orjson'
$ uv sync --locked --no-dev
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
С --frozen образ собирается без единого предупреждения и падает уже в рантайме, на импорте. В гайде по Docker --frozen стоит только в промежуточном слое. Туда смонтирован один uv.lock, без pyproject.toml, и сверять lock не с чем. Финальный uv sync там идёт с --locked. В репозитории с примерами пошли дальше: pyproject.toml монтируется и в первый шаг, и оба вызова идут с --locked.
Когда шаблон копируют кусками, --frozen часто переезжает и в финальный шаг. Сверка lock пропускается, и lock, который разошёлся с проектом, доезжает до продакшена. Проверить это можно и до Docker: uv lock --check в CI делает то же, что --locked у остальных команд.
Последнее отличие сборку не ломает, зато его видно на каждом старте. pip при установке компилирует .py в .pyc, если его не попросить об обратном. uv по умолчанию не компилирует. Это заметная часть времени установки, а на машине разработчика байткод всё равно появится при первом запуске. В контейнере первый запуск бывает каждый раз.
Ставим fastapi 0.120.0, pandas 3.0.6 и sqlalchemy 2.0.44 на Python 3.13 двумя способами и меряем импорт всех трёх. PYTHONDONTWRITEBYTECODE=1 здесь изображает корень только для чтения, где Python не может сохранить скомпилированное:
без компиляции, pyc не пишется запуск 1 2.27 с запуск 2 2.14 с запуск 3 2.17 с
без компиляции, pyc пишется запуск 1 2.17 с запуск 2 0.61 с
UV_COMPILE_BYTECODE=1 запуск 1 0.68 с запуск 2 0.68 с запуск 3 0.68 с
размер окружения 141 МБ без компиляции, 181 МБ с ней
Без байткода каждый старт стоит около 2,2 секунды вместо 0,7. Разница втрое. При read-only корне так будет на каждом рестарте, и под с короткой startup-пробой почувствует это первым. Платим за ускорение 40 МБ образа и временем сборки. В гайде Astral этому посвящён отдельный раздел с важной оговоркой: в официальном образе python стандартная библиотека тоже не скомпилирована, и UV_COMPILE_BYTECODE её не касается.
Рядом, в подразделе про кэширование, живёт UV_LINK_MODE=copy. Кэш в --mount=type=cache лежит на другой файловой системе, и uv не может сделать hardlink из кэша в окружение:
warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
If the cache and target directories are on different filesystems, hardlinking may not be supported.
If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
Предупреждение безвредное. uv и так копирует файлы. Переменная его выключает и заодно фиксирует, что копирование тут задумано.
Если трогать что-то одно, то .python-version в репозитории и его COPY в образ до uv sync. Остальные пять мест дают медленный старт, лишние пакеты или ошибку на запуске, которую видно сразу. Без пина и с uv из latest образ ломается сам — в день релиза uv, без единого коммита в вашем репозитории.

ИИ-инструменты тоже добавляют в разработку неочевидное поведение [6]: сгенерированный код может выглядеть корректно, но требовать дополнительной проверки.
На бесплатном вебинаре «Инструменты на базе ИИ для Python-разработчиков»
19 ноября в 20:00разберём, какие задачи стоит делегировать искусственному интеллекту [7], как использовать его для рефакторинга, поиска ошибок и написания тестов, а также по каким критериям выбирать модели для работы с кодом. Записаться [8]
Автор: badcasedaily1
Источник [9]
Сайт-источник BrainTools: https://www.braintools.ru
Путь до страницы источника: https://www.braintools.ru/article/38726
URLs in this post:
[1] Python: https://otus.pw/gi6Y/
[2] вступительного теста: https://otus.pw/aGgJW/
[3] Ошибка: http://www.braintools.ru/article/4192
[4] памяти: http://www.braintools.ru/article/4140
[5] поведение: http://www.braintools.ru/article/9372
[6] поведение: http://www.braintools.ru/article/5593
[7] интеллекту: http://www.braintools.ru/article/7605
[8] Записаться: https://otus.pw/PXrc/
[9] Источник: https://habr.com/ru/companies/otus/articles/1096480/?utm_source=habrahabr&utm_medium=rss&utm_campaign=1096480
Нажмите здесь для печати.