Crea imágenes Docker Python multi-stage livianas: dependencias bloqueadas, usuario sin shell y Gunicorn en lugar del servidor de desarrollo.
Respuesta rápida: separa en un Dockerfile multi-stage lo que hace falta para construir de lo que hace falta para ejecutar, y copia a la imagen final solo lo instalado:
FROM python:3.12-slim AS builder
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --upgrade pip \
&& pip install --no-cache-dir --prefix=/install -r requirements.txt
FROM python:3.12-slim AS runtime
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY --from=builder /install /usr/local
COPY . .
CMD ["python", "app.py"]Constrúyela con docker build -t api-python:prod . y compara el tamaño con docker image ls api-python:prod.
Nivel: intermedio · Requiere: Docker y una app Python con requirements.txt
Aprende a optimizar imágenes Docker para aplicaciones Python usando builds multi-stage, dependencias bloqueadas y buenas prácticas de seguridad. Esta guía muestra cómo reducir el tamaño de la imagen, mejorar los tiempos de despliegue y preparar una base más confiable para producción.
Las imágenes Docker demasiado grandes generan varios problemas: tardan más en construirse, ralentizan los despliegues, consumen más almacenamiento, hacen más lento el CI/CD y aumentan la superficie de ataque.
En aplicaciones Python esto suele ocurrir cuando se instala todo dentro de una única imagen: compiladores, dependencias de build, cachés de paquetes, archivos temporales y herramientas que no son necesarias en producción.
Una forma práctica de resolverlo es utilizar builds multi-stage, bloquear dependencias y separar claramente lo que se necesita para construir la aplicación de lo que realmente se necesita para ejecutarla.
En esta guía vas a construir una imagen Docker Python más liviana, reproducible y preparada para servidores cloud como DonWeb Cloud, instancias Linux propias o entornos de laboratorio.
Qué vas a lograr
Al finalizar este tutorial tendrás:
- una imagen Python más liviana;
- un
Dockerfilebasado en multi-stage build; - dependencias instaladas de forma más controlada;
- una imagen final sin herramientas innecesarias de compilación;
- comandos para construir, ejecutar y validar la imagen;
- una base más segura para llevar la aplicación a producción.
El objetivo no es aplicar una optimización extrema, sino construir una imagen más limpia, verificable y fácil de mantener.
¿Cuándo conviene una imagen Docker Python multi-stage?
Este enfoque resulta útil cuando:
- la imagen tarda demasiado en construirse;
- el despliegue en cloud se vuelve lento;
- el pipeline de CI/CD consume demasiado tiempo;
- quieres reducir superficie de ataque;
- necesitas builds más reproducibles;
- quieres separar dependencias de desarrollo y producción;
- la aplicación va a ejecutarse en un servidor cloud o entorno productivo.
También es recomendable cuando el proyecto empieza a crecer y el Dockerfile original ya no resulta fácil de auditar.
Requisitos previos
Antes de comenzar asegúrate de contar con:
- Docker Engine instalado;
- acceso a una terminal;
- un proyecto Python funcional;
- archivo
requirements.txto equivalente; - un endpoint de prueba, por ejemplo
/health; - permisos para construir y ejecutar imágenes Docker;
- un entorno de laboratorio antes de aplicar cambios en producción.
Si el servidor ya tiene tráfico real, realiza una copia de seguridad y define una ruta de rollback antes de reemplazar imágenes o reiniciar servicios.
Estructura recomendada del proyecto
Una estructura mínima podría ser la siguiente:
app/
├── app.py
├── requirements.txt
├── Dockerfile
└── .dockerignoreEn proyectos más grandes puede haber otros directorios, como src/, tests/, migrations/, static/ o config/. Lo importante es que la imagen final copie únicamente lo necesario para ejecutar la aplicación.
Paso 1. Bloquear las dependencias
Antes de optimizar la imagen, revisa cómo se instalan las dependencias.
Un archivo poco controlado como este puede generar builds diferentes con el paso del tiempo:
flask
requests
gunicornPara producción conviene utilizar versiones explícitas:
flask==X.Y.Z
requests==X.Y.Z
gunicorn==X.Y.ZDe esta forma, cada build será más predecible y más fácil de auditar.
También puedes usar herramientas como pip-tools, Poetry o uv para generar archivos de lock. La decisión depende del flujo de trabajo del equipo, pero el principio es el mismo: evitar instalaciones ambiguas en producción.
Paso 2. Crear un .dockerignore
El archivo .dockerignore evita copiar al contexto de build archivos innecesarios.
Crea un archivo llamado .dockerignore con una base como esta:
.git
.gitignore
__pycache__/
*.pyc
*.pyo
*.pyd
.env
.venv/
venv/
dist/
build/
.pytest_cache/
.mypy_cache/
.coverage
tests/
docs/Esto ayuda a reducir el tamaño del contexto enviado a Docker y evita incluir archivos sensibles o irrelevantes dentro de la imagen.
Nunca copies archivos .env, credenciales, claves privadas o secretos dentro de la imagen.
Paso 3. Crear un Dockerfile multi-stage
Un build multi-stage permite usar una etapa para instalar o compilar dependencias y otra etapa más liviana para ejecutar la aplicación.
Ejemplo base:
FROM python:3.12-slim AS builder
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --upgrade pip \
&& pip install --no-cache-dir --prefix=/install -r requirements.txt
FROM python:3.12-slim AS runtime
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY --from=builder /install /usr/local
COPY . .
CMD ["python", "app.py"]La primera etapa instala las dependencias. La segunda etapa copia únicamente lo necesario para ejecutar la aplicación.
Esto evita arrastrar al runtime archivos temporales, cachés o herramientas que solo fueron necesarias durante la construcción.
Paso 4. Construir la imagen
Desde el directorio del proyecto ejecuta:
docker build -t api-python:prod .Cuando finalice el build, verifica que la imagen exista:
docker image ls api-python:prodTambién puedes inspeccionar el historial de capas:
docker history api-python:prodEste comando ayuda a detectar capas demasiado grandes o instrucciones que podrían optimizarse.
Paso 5. Ejecutar la imagen localmente
Prueba la imagen antes de moverla a un servidor productivo.
docker run --rm -p 8000:8000 api-python:prodEn otra terminal, valida que la aplicación responda:
curl http://localhost:8000/healthSi tu aplicación no expone /health, reemplaza la ruta por un endpoint real.
La prueba mínima debería confirmar que:
- el contenedor inicia correctamente;
- la aplicación queda escuchando en el puerto esperado;
- las dependencias se instalaron sin errores;
- el endpoint de validación responde.
Paso 6. Revisar el tamaño de la imagen
Compara el tamaño de la imagen resultante:
docker image ls api-python:prodSi quieres analizar qué capas ocupan más espacio:
docker history api-python:prodUna imagen más pequeña suele mejorar:
- tiempos de build;
- tiempos de pull;
- uso de almacenamiento;
- velocidad de despliegue;
- eficiencia del pipeline CI/CD.
La reducción exacta dependerá de las dependencias, la imagen base y los archivos copiados al contenedor.
Paso 7. Preparar la imagen para producción
Antes de usar la imagen en producción, revisa algunos puntos básicos.
Evita ejecutar el proceso como root. Puedes crear un usuario no privilegiado dentro del Dockerfile:
RUN useradd --create-home --shell /usr/sbin/nologin appuser
USER appuserUn ejemplo integrado en la etapa runtime podría quedar así:
FROM python:3.12-slim AS runtime
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY --from=builder /install /usr/local
COPY . .
RUN useradd --create-home --shell /usr/sbin/nologin appuser \
&& chown -R appuser:appuser /app
USER appuser
CMD ["python", "app.py"]Si la aplicación necesita escribir archivos temporales, define rutas específicas para eso. No conviene habilitar escritura general si no es necesario.
Configuración base recomendada
Una versión más completa del Dockerfile podría quedar así:
FROM python:3.12-slim AS builder
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY requirements.txt .
RUN pip install --upgrade pip \
&& pip install --no-cache-dir --prefix=/install -r requirements.txt
FROM python:3.12-slim AS runtime
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
COPY --from=builder /install /usr/local
COPY . .
RUN useradd --create-home --shell /usr/sbin/nologin appuser \
&& chown -R appuser:appuser /app
USER appuser
EXPOSE 8000
CMD ["python", "app.py"]Para aplicaciones web Python, en producción suele ser preferible ejecutar la app con un servidor como Gunicorn en lugar de python app.py.
Por ejemplo:
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]Ajusta app:app según el nombre real de tu módulo y de tu aplicación.
Problemas frecuentes
La imagen sigue siendo demasiado grande
Revisa si estás copiando archivos innecesarios. El primer lugar para mirar es .dockerignore.
También verifica si alguna dependencia instala paquetes pesados que podrían separarse, reemplazarse o instalarse solo cuando sean necesarios.
El build falla al instalar dependencias
Algunas librerías Python necesitan paquetes del sistema para compilarse. En ese caso, instala esas dependencias solo en la etapa builder y evita copiarlas a la imagen final salvo que sean necesarias en runtime.
El contenedor inicia pero la app no responde
Revisa que la aplicación escuche en 0.0.0.0 y no únicamente en localhost.
También valida el puerto expuesto, el comando de inicio y los logs del contenedor:
docker logs <container_id>El endpoint /health no existe
Puedes crear uno simple en la aplicación o reemplazarlo por una ruta real que confirme que el servicio está activo.
Lo importante es contar con una verificación objetiva antes de publicar cambios.
Faltan variables de entorno
No incluyas secretos dentro de la imagen. Pasa las variables en tiempo de ejecución:
docker run --rm -p 8000:8000 --env-file .env api-python:prodRecuerda que el archivo .env debe estar excluido del build mediante .dockerignore.
Buenas prácticas para producción
Para mantener imágenes Python más seguras y eficientes:
- usa imágenes base livianas y oficiales;
- bloquea versiones de dependencias;
- evita copiar archivos innecesarios;
- no incluyas secretos dentro de la imagen;
- ejecuta la aplicación con un usuario no root;
- separa dependencias de build y runtime;
- elimina cachés de instalación;
- analiza periódicamente vulnerabilidades;
- mantén un endpoint de healthcheck;
- documenta cómo construir, ejecutar y revertir la imagen.
Estas prácticas no reemplazan otras capas de seguridad, pero ayudan a construir una base más mantenible y auditable.
Consideraciones de seguridad
No publiques una imagen en producción sin probarla antes en un entorno controlado.
Antes de desplegar:
- verifica que no haya credenciales dentro de la imagen;
- revisa el historial de capas;
- escanea dependencias y paquetes del sistema;
- confirma que la aplicación no corre como root;
- valida que las variables sensibles se inyecten en runtime;
- conserva la versión anterior para rollback.
Si detectas credenciales expuestas en una imagen ya publicada, rota esas credenciales antes de continuar con el análisis.






Siguiente paso
Para seguir con este tema, estas guías del blog te sirven como próximo paso: