Docker Compose: diferencia entre down y stop

La respuesta breve

docker compose stop detiene los contenedores y los conserva en el disco. docker compose down los detiene y después elimina los contenedores y la red que Compose creó para el proyecto. Ninguno de los dos comandos afecta a un volumen con nombre. La base de datos solo se elimina cuando se añade -v, como en docker compose down -v, que elimina los volúmenes con nombre declarados en la sección volumes del archivo de Compose.

Esa es toda la diferencia en un párrafo. El resto de esta guía lo demuestra con un volumen de Postgres cuya persistencia puede comprobarse después de ejecutar down y que desaparece al ejecutar down -v. También explica los dos casos en los que se necesita --force-recreate.

docker compose stop: los contenedores permanecen detenidos

stop envía SIGTERM al proceso principal de cada contenedor y espera. Después envía SIGKILL si el proceso todavía está activo. La espera predeterminada es de 10 segundos y -t permite cambiarla. No se elimina nada. El contenedor conserva su ID, su capa escribible, su reserva de IP y sus registros.

docker compose stop
docker compose ps -a

docker compose ps por sí solo muestra únicamente los contenedores en ejecución. Por eso, después de stop muestra una tabla vacía y parece que los contenedores han desaparecido. ps -a también incluye los detenidos. Ahí verá Exited (0) junto a cada servicio. Vuelva a iniciarlos con docker compose start, que reutiliza exactamente los mismos contenedores.

Como los contenedores todavía existen, todo lo escrito en ellos fuera de un volumen permanece allí. Esto incluye un paquete instalado manualmente con docker compose exec y un archivo de configuración editado dentro del contenedor. Por este motivo práctico conviene usar stop durante la depuración: puede reiniciar con el mismo estado.

docker compose down: se eliminan los contenedores y las redes

down detiene los contenedores y después los elimina, junto con la red predeterminada que Compose creó para el proyecto. La documentación de Docker lo describe como una operación que detiene y elimina los contenedores, las redes, los volúmenes y las imágenes creados por up, pero los volúmenes y las imágenes solo se eliminan cuando se solicitan mediante -v y --rmi.

docker compose down
docker compose ps -a
docker network ls

Después de down, ps -a no muestra nada para el proyecto y la red <project>_default ya no existe. El nombre del proyecto procede del nombre del directorio, a menos que establezca name: en el archivo de Compose o pase -p. Todos los cambios realizados dentro de la capa escribible de un contenedor son irrecuperables. Por tanto, trate down como un comando que descarta el contenedor y conserva los datos almacenados en los volúmenes.

Si lo ejecuta en el directorio equivocado, aparece no configuration file provided: not found. Compose no sabe a qué proyecto se refiere y se niega a continuar. Use docker compose -f /srv/myapp/compose.yaml down cuando no se encuentre en el directorio del proyecto.

¿docker compose down elimina mis volúmenes?

No. Un volumen con nombre declarado bajo la clave de nivel superior volumes sobrevive a down y al contenedor al que estaba asociado. Este es el temor más común sobre el comando. La respuesta es la misma en Compose v2.

Prepare una pila que pueda probar. Coloque lo siguiente en compose.yaml, dentro de un directorio vacío llamado voltest.

services:
  db:
    image: postgres:16.4
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Iníciela y escriba una fila que pueda reconocer más adelante.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"

Ahora elimine el contenedor y compruebe el volumen.

docker compose down
docker volume ls

La salida sigue mostrando voltest_pgdata. El contenedor ya no existe, pero los datos permanecen. Vuelva a iniciar la pila y lea la fila.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"

Obtendrá una fila que contiene survived. El contenedor nuevo es distinto y tiene un ID diferente, pero está asociado al mismo volumen. Para conocer el contexto completo, la guía sobre los conceptos básicos de Compose explica los volúmenes con nombre frente a los montajes bind y dónde reside realmente cada uno en el host.

Qué destruye exactamente down -v

-v (forma larga --volumes) elimina los volúmenes con nombre declarados en la sección volumes del archivo de Compose, además de los volúmenes anónimos asociados a los contenedores. Ejecútelo en la misma pila.

docker compose down -v
docker volume ls

voltest_pgdata ya no aparece en la lista. Inicie la pila de nuevo. El punto de entrada de Postgres encuentra un directorio de datos vacío e inicializa un clúster nuevo. El registro del contenedor lo indica claramente.

The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.

Si aparece ese bloque en una pila que lleva meses en ejecución, significa que se eliminó el volumen. La tabla marker ha desaparecido y la única forma de recuperarla es usar una copia de seguridad.

-v nunca elimina algunos tipos de almacenamiento. Un montaje bind es una ruta del host. Docker solo lo desmonta y los archivos permanecen donde estaban. Un volumen marcado como external: true se declara como perteneciente a algo externo a este proyecto. Compose nunca lo elimina. Un volumen con nombre que eliminó del archivo de Compose antes de ejecutar down -v ya no está declarado. Compose no sabe que debe eliminarlo y lo deja como huérfano en docker volume prune.

Este último caso suele aparecer durante una refactorización. Elimine un servicio y su volumen del archivo, ejecute down -v y el volumen permanecerá porque el archivo ya no lo menciona. Ejecute down -v antes de editar el archivo, no después.

Cuándo necesita realmente --force-recreate

docker compose up -d no reconstruye todo cada vez. Compose almacena un hash de la configuración resuelta de cada servicio en el contenedor como una etiqueta. Si el hash coincide y el ID de la imagen coincide, el contenedor no se modifica y obtiene Container voltest-db-1 Running en lugar de Recreated. Este es el comportamiento que necesita casi siempre, porque permite ejecutar up -d repetidamente de forma segura.

Por eso algunos cambios parecen no tener efecto. Compose calcula el hash de la definición de servicio resuelta, no del contenido de los archivos a los que apunta esa definición. Un archivo de configuración montado en el contenedor y leído una sola vez durante el inicio no activa la recreación al editarlo, porque la ruta de montaje no cambió. El servicio sigue ejecutándose con los valores que leyó al arrancar.

docker compose up -d --force-recreate

Detiene y elimina cada contenedor, y crea uno nuevo a partir de la misma definición. Úselo después de editar un archivo de configuración montado y cuando un contenedor haya quedado en un estado que no pueda explicar. Los volúmenes no se modifican, por lo que una base de datos sobrevive a una recreación forzada. Para obtener una imagen más reciente con la misma etiqueta, también necesita ejecutar la operación de descarga.

docker compose pull
docker compose up -d

pull obtiene el nuevo ID de la imagen, y up -d detecta que el ID de la imagen es diferente del del contenedor en ejecución y lo recrea automáticamente. Añadir --force-recreate sin pull le proporciona un contenedor nuevo a partir de la misma imagen antigua. Por eso es tan frecuente la queja «hice una recreación forzada y sigue siendo la versión antigua».

docker compose restart no hace nada de esto. Reinicia los contenedores existentes y no vuelve a leer el archivo de Compose, por lo que no se aplicará una variable de entorno modificada ni un mapeo de puertos modificado. Si editó el archivo, use up -d.

El modelo mental que debe conservar

Los contenedores se pueden reemplazar. Un contenedor es un proceso más una capa fina escribible, y Compose puede crear otro idéntico a partir del archivo en aproximadamente un segundo. Los volúmenes no se pueden reemplazar, porque contienen la única copia del estado que ningún archivo del repositorio puede regenerar.

Cada verbo de Compose corresponde a esa separación. stop y start conservan el contenedor. down y up reemplazan el contenedor y conservan el volumen. down -v es el único comando habitual que elimina el estado, por lo que necesita un indicador explícito. Antes de escribirlo en un entorno real, confirme que tiene una copia de seguridad que ya haya restaurado al menos una vez.

La misma lógica se aplica a los secretos. Una contraseña establecida mediante POSTGRES_PASSWORD solo se lee la primera vez que se inicializa la base de datos, por lo que cambiarla en el archivo de entorno y ejecutar up -d le proporciona password authentication failed for user "postgres". El contenedor es nuevo y el volumen es antiguo, y el volumen antiguo todavía contiene la contraseña anterior. Cómo resuelve Compose los archivos de entorno y los secretos explica qué capa prevalece cuando la misma variable se establece dos veces.

Modos de fallo y los mensajes que verá

no configuration file provided: not found significa que Compose se está ejecutando en un directorio sin compose.yaml ni docker-compose.yml. Pase -f con la ruta completa.

network voltest_default has active endpoints en down significa que un contenedor externo a este proyecto está conectado a la red del proyecto. Normalmente, se inició manualmente con docker run --network. Elimine ese contenedor y vuelva a ejecutar down.

Found orphan containers ([voltest-old-1]) for this project aparece después de cambiar el nombre de un servicio o eliminarlo. El contenedor antiguo todavía conserva la etiqueta del proyecto. docker compose down --remove-orphans los elimina y es seguro ejecutarlo en una pila en buen estado.

Error response from daemon: remove voltest_pgdata: volume is in use en un docker volume rm manual significa que algún contenedor todavía hace referencia al volumen, incluso uno detenido. Ejecute primero docker compose down y después elimine el volumen, o use directamente down -v. En un proyecto más grande, una pila de Compose con varios servicios muestra cuántos volúmenes puede acumular un proyecto.

FAQ

¿docker compose down elimina mi base de datos?

No, si la base de datos está en un volumen con nombre o en un bind mount. down elimina los contenedores y la red del proyecto, pero el volumen permanece en el disco con sus datos intactos. El siguiente docker compose up -d conecta un contenedor nuevo al mismo volumen y los datos siguen disponibles. Solo docker compose down -v elimina los volúmenes con nombre, y únicamente los declarados en la sección volumes del archivo Compose.

¿Cuál es la diferencia entre stop y down para un contenedor que quiero volver a usar?

stop conserva el contenedor, por lo que docker compose start te devuelve al mismo contenedor con la misma capa escribible. Todo lo que hayas instalado o editado manualmente dentro del contenedor sigue presente. down elimina el contenedor, por lo que el siguiente up -d crea uno nuevo a partir de la imagen y se pierden esos cambios manuales. Mientras depuras, usa stop.

¿Cómo elimino todo lo que creó un proyecto de Compose?

docker compose down -v --rmi all --remove-orphans elimina los contenedores, la red del proyecto, los volúmenes con nombre declarados en el archivo, las imágenes que usaron los servicios y cualquier contenedor que todavía tenga la etiqueta con el nombre del proyecto. No modifica los bind mounts ni los volúmenes marcados con external: true. Comprueba lo que estás a punto de perder con docker volume ls antes de ejecutarlo.

¿Por qué mi contenedor ignora el cambio que hice en un archivo de configuración montado?

Compose decide si debe volver a crear un contenedor comparando un hash de la definición de servicio resuelta. Ese hash no incluye el contenido de un archivo montado. La ruta no cambió, por lo que Compose deja el contenedor en ejecución con los valores que leyó al iniciarse. Ejecuta docker compose up -d --force-recreate para crear un contenedor nuevo que vuelva a leer el archivo.

¿Por qué mi nuevo POSTGRES_PASSWORD no funciona después de cambiarlo?

La imagen de Postgres solo lee POSTGRES_PASSWORD cuando inicializa un directorio de datos vacío. Tu volumen ya contiene un clúster inicializado, por lo que la variable se ignora y sigue aplicándose la contraseña anterior. Verás password authentication failed for user "postgres". Cambia la contraseña con ALTER USER dentro de la base de datos en ejecución, o acepta perder los datos y empieza de nuevo con docker compose down -v.