Builds multi-stage de Docker para Django con uv: build, venv e imagen final ligera



Una imagen de Django construida directo con pip install -r requirements.txt en una sola etapa arrastra un toolchain de C, la caché de pip y listas de apt que solo hacían falta para compilar psycopg[c]. Multi-stage más uv se deshace de todo eso: una etapa resuelve e instala dependencias en un venv, la otra copia solo ese venv y el código de la app sobre una base ligera.

El Dockerfile

# syntax=docker/dockerfile:1
FROM python:3.13-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv
WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project --no-dev
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

FROM python:3.13-slim AS runtime
RUN groupadd -r app && useradd -r -g app app
WORKDIR /app
COPY --from=builder --chown=app:app /app/.venv /app/.venv
COPY --from=builder --chown=app:app /app /app
ENV PATH="/app/.venv/bin:$PATH" PYTHONUNBUFFERED=1
USER app
EXPOSE 8000
CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000"]
Etapa de build y etapa final para una imagen de Django con uvbuilderpython:3.13-slim+ uvCOPY pyproject.toml uv.lockRUN uv sync --frozen --no-devgenera /app/.venv~210 MB, se descarta al terminarruntimepython:3.13-slimCOPY --from=builder /app/.venvCOPY . .ENV PATH=/app/.venv/bin:$PATHCMD gunicorn config.wsgi~140 MB imagen finalsolo el venv

Por qué dos RUN de uv sync

El primer uv sync --no-install-project instala solo las dependencias de terceros, antes de que COPY . . traiga el código de tu app. Eso significa que editar una vista o una plantilla no invalida la capa de dependencias -- la caché de Docker depende de la instrucción del Dockerfile y de los archivos que lee, y pyproject.toml/uv.lock no cambiaron. El segundo uv sync instala tu propio paquete en modo editable una vez que el código ya está ahí. Si te saltas esa separación, cada rebuild reinstala Django, psycopg y el resto desde cero.

Trucos de caché de capas que de verdad importan

  • Copia pyproject.toml y uv.lock antes de COPY . ., siempre. Es la ganancia más grande -- es la diferencia entre un rebuild de 2-3 segundos y uno de 40+ en cada cambio de código.
  • Monta la caché propia de uv con --mount=type=cache,target=/root/.cache/uv. uv cachea los wheels por versión, así que incluso con la caché de capas fría reaprovecha la descarga entre builds en la misma máquina o runner de CI con persistencia de caché activada.
  • Fija la versión de uv que copias (uv:0.5 arriba, no :latest) -- una subida de versión de uv en origen no debería invalidar en silencio todas las capas de abajo en tu próximo build.
  • UV_COMPILE_BYTECODE=1 precompila los .pyc en tiempo de build en vez de en la primera petición dentro del contenedor final, vale la pena en cuanto corres más de una réplica.
  • No copies uv mismo a la etapa final. El builder lo necesita, el contenedor en producción solo necesita el intérprete dentro del venv y nunca vuelve a llamar a uv.

Lo que esto te da

En nuestro propio CI, el antes/después se ve así: un build en frío (sin caché alguna) tomaba 51 segundos con pip y una sola etapa, imagen final de 480 MB. Al pasar al build de dos etapas con uv de arriba: build en frío 34 segundos, imagen final de 142 MB, y un rebuild que solo toca código de la app -- sin cambios de dependencias -- termina en unos 2.5 segundos porque cada capa hasta COPY . . viene de caché. Ese es el número que realmente importa en el día a día: cuánto esperas entre guardar un archivo y verlo corriendo en un contenedor.

Dejar un comentario

Los comentarios anónimos se publican tras ser revisados.