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"]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.tomlyuv.lockantes deCOPY . ., 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.5arriba, 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=1precompila los.pycen 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
uvmismo 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 auv.
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.

