tutorial de Docker Compose: comandos habituales y cómo usarlos

Ejecuta todos los comandos docker compose desde la carpeta donde está compose.yaml (o desde una subcarpeta), o especifica el archivo con -f. Puedes añadir el nombre de un servicio al comando para actuar solo sobre ese servicio; si no lo añades, se aplica a todo el proyecto. Los ejemplos de esta sección usan el proyecto compose-demo de Introducción a Compose.

Iniciar y detener

Consulta los resultados reales de up, stop, start y down en Introducción a Compose.

Consultar el estado

$ docker compose ps
NAME                     IMAGE               COMMAND                  SERVICE   CREATED          STATUS         PORTS
compose-demo-adminer-1   adminer             "entrypoint.sh docke…"   adminer   10 seconds ago   Up 9 seconds   0.0.0.0:8081->8080/tcp, [::]:8081->8080/tcp
compose-demo-db-1        postgres:18         "docker-entrypoint.s…"   db        10 seconds ago   Up 9 seconds   5432/tcp
compose-demo-web-1       nginx:1.30-alpine   "/docker-entrypoint.…"   web       10 seconds ago   Up 8 seconds   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

$ docker compose ls
NAME                STATUS              CONFIG FILES
compose-demo        running(3)          /work/compose-demo/compose.yaml

$ docker compose images
CONTAINER                REPOSITORY          TAG                 PLATFORM            IMAGE ID            SIZE                CREATED
compose-demo-adminer-1   adminer             latest              linux/amd64         74f29c416e14        164MB               2 weeks ago
compose-demo-db-1        postgres            18                  linux/amd64         74935e722416        644MB               6 days ago
compose-demo-web-1       nginx               1.30-alpine         linux/amd64         0985e772fb9f        92.8MB              2 weeks ago

$ docker compose top web
SERVICE  #   PID    USER  TIME  COMMAND
web      1   21356  root  0:00  nginx: master process nginx -g daemon off;
web      1   21425  101   0:00  nginx: worker process

Consultar los registros

$ docker compose logs --tail 2 -t web
web-1  | 2026-10-13T00:18:19.618825771Z 2026/10/13 00:18:19 [notice] 1#1: start worker processes
web-1  | 2026-10-13T00:18:19.619080382Z 2026/10/13 00:18:19 [notice] 1#1: start worker process 30

docker compose logs               # Todos los servicios
docker compose logs -f app        # Sigue los registros de app
docker compose logs --tail 50 -t  # Últimas 50 líneas, con hora

Ejecutar comandos en un servicio

exec: dentro de un contenedor en ejecución

$ docker compose exec web nginx -v
nginx version: nginx/1.30.5

$ docker compose exec db psql -U postgres -c "SELECT now();"
              now
-------------------------------
 2026-10-13 00:18:28.618314+00
(1 row)


$ docker compose exec -T db pg_dump -U postgres postgres > backup.sql && wc -l backup.sql
27 backup.sql

$ rm backup.sql

• Usa el nombre del servicio (web, db) para indicar el contenedor, sin preocuparte por el nombre real del contenedor.
• -T desactiva el terminal virtual. Debes añadirlo al redirigir la salida a un archivo (por ejemplo, pg_dump > backup.sql, como arriba) o al usarlo en un script; de lo contrario, la salida podría incluir caracteres de control del terminal.
• docker compose exec web sh abre un shell interactivo.

run: abrir un nuevo contenedor temporal

$ docker compose run --rm web nginx -t
Container compose-demo-web-run-80040d25219f Creating
Container compose-demo-web-run-80040d25219f Created
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

run usa la configuración del servicio (imagen, variables de entorno, Volume y red) para crear un contenedor nuevo y ejecutar el comando (con el nombre compose-demo-web-run-…). --rm lo elimina automáticamente al terminar. En el ejemplo, se usa para comprobar la configuración de nginx (nginx -t) sin afectar al servicio que está en ejecución.

Después de modificar la configuración: restart no basta, usa up -d

Este es el malentendido más común. Prueba: añade la variable de entorno SITE_TITLE: v2 al servicio web en compose.yaml y luego prueba restart y up -d por separado:

$ docker compose --progress plain restart web
 Container compose-demo-web-1 Restarting
 Container compose-demo-web-1 Started

$ docker compose exec web sh -c "echo SITE_TITLE=\$SITE_TITLE"
SITE_TITLE=

$ docker compose up -d
[+] up 3/3
 ✔ Container compose-demo-db-1      Running                                                     0.0s
 ✔ Container compose-demo-adminer-1 Running                                                     0.0s
 ✔ Container compose-demo-web-1     Started                                                     0.4s

$ docker compose exec web sh -c "echo SITE_TITLE=\$SITE_TITLE"
SITE_TITLE=v2

• restart solo detiene y vuelve a iniciar el contenedor existente. La configuración del contenedor queda determinada al crearlo, por eso no aparece la nueva variable de entorno (SITE_TITLE= está vacío).
• up -d compara compose.yaml con los contenedores existentes. Al detectar que cambió la configuración de web, lo recrea (Started); db y adminer, cuya configuración no cambió, siguen igual (Running).

Después de modificar compose.yaml o .env, usa siempre docker compose up -d.

Compilar imágenes

docker compose build              # Compila todos los servicios que tengan una configuración build
docker compose build --no-cache app
docker compose pull               # Descarga las imágenes más recientes de todos los servicios
docker compose push               # Envía los servicios que tengan un nombre de imagen

$ docker compose pull
[+] pull 3/3
 ✔ Image adminer           Pulled                                                               0.7s
 ✔ Image nginx:1.30-alpine Pulled                                                               0.5s
 ✔ Image postgres:18       Pulled                                                               1.3s

Flujo habitual para actualizar los servicios que usan imágenes existentes:

docker compose pull
docker compose up -d
docker image prune -f   # Elimina las imágenes antiguas que fueron reemplazadas

Comprobar la configuración

$ docker compose config --services
db
adminer
web

$ docker compose config --volumes
pgdata

$ docker compose port web 80
0.0.0.0:8080

docker compose config             # Muestra la configuración completa tras combinar archivos y sustituir variables
docker compose config --services  # Muestra todos los nombres de los servicios
docker compose config --volumes   # Muestra los Volume
docker compose port web 80        # Indica a qué puerto del host corresponde un puerto del contenedor del servicio

Consulta un ejemplo de la salida completa de docker compose config en Sintaxis de compose.yaml.

Otros comandos

docker compose cp web:/etc/nginx/nginx.conf ./nginx.conf   # Copia un archivo
docker compose watch                                       # Detecta cambios en archivos y los sincroniza o reconstruye automáticamente durante el desarrollo
docker compose up -d --scale worker=3                      # Inicia 3 worker

Opciones globales

Estas opciones se escriben entre docker compose y el subcomando:

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose -p myproject up -d          # Especifica el nombre del proyecto
docker compose --env-file .env.prod up -d  # Especifica el archivo .env
docker compose --profile tools up -d       # Activa el perfil
 docker compose --progress plain up -d      # Muestra el progreso en texto sin formato (útil para los registros de CI)

Resumen de situaciones habituales

Resumen

• Después de modificar compose.yaml o .env, usa siempre docker compose up -d.
• Usa exec con un contenedor en ejecución y run --rm para abrir un contenedor temporal.
• Usa docker compose config para comprobar la configuración final combinada.
• Consulta todas las opciones de up y down en docker compose up y docker compose down.

Ejercicios

Ejercicio 1: Modifica el puerto del host de web en compose.yaml y prueba docker compose restart web y docker compose up -d por separado. ¿Cuál aplica el nuevo puerto?

Ejercicio 2: Usa un contenedor temporal para ejecutar psql --version en la red del servicio db y elimina automáticamente el contenedor al terminar.

docker compose run --rm db psql --version

Actualizado 14 de octubre de 2026