Cómo instalar Docker Compose: Linux, macOS y Windows

¿Tienes Docker en marcha y dominas los comandos básicos, pero te cansa iniciar los contenedores uno a uno?

Docker Compose es una herramienta que te permite definir y ejecutar aplicaciones con varios contenedores desde un único archivo YAML. La parte confusa es que circulan dos versiones: el binario independiente antiguo (v1) y el nuevo complemento de la CLI (v2). Muchos tutoriales no especifican cuál usan, así que terminas siguiendo pasos que no encajan con tu entorno.

Docker Compose v2 es un plugin incluido en las instalaciones modernas de Docker, lo que simplifica mucho la instalación, ejecución y verificación. El proceso ya no es tan manual como antes.

En este artículo, te explico cómo instalar Docker Compose en Linux, macOS y Windows de la forma correcta, usando v2.

¿Eres nuevo en los conceptos de virtualización y contenedores? Lee nuestro reciente Docker para principiantes para practicar desde el primer minuto.

Antes de instalar Docker Compose

Antes de nada, necesitas Docker Engine en tu equipo. Docker Compose no funciona por sí solo: necesita Docker.

Ejecuta este comando para comprobar tu versión de Docker:

docker --version

Versión de Docker instalada

Si Docker no está instalado, detente aquí e instálalo primero. Si ya lo tienes, comprueba si Compose está disponible:

docker compose version

Versión de Docker Compose instalada

Si devuelve un número de versión, listo: Compose v2 ya viene incluido con tu instalación de Docker. Puedes saltar directamente a la sección de verificación.

Si en su lugar ves un mensaje genérico de comando no encontrado, sigue leyendo.

Esta es la diferencia clave que debes conocer:

• Docker Compose v1 es el binario independiente legado. Se invocaba con docker-compose (con guion). Está obsoleto y ya no se mantiene.

• Docker Compose v2 es un plugin de la CLI que se distribuye con Docker moderno. Se invoca con docker compose (sin guion).

Si usas una instalación reciente de Docker, casi seguro que ya tienes v2. El resto del artículo asume v2.

Instalar Docker Compose en Linux

En Linux, tienes dos formas de obtener Docker Compose. La primera usa el repositorio oficial de Docker: es la opción recomendada. La segunda es una instalación manual útil cuando no puedes usar un gestor de paquetes o necesitas una versión específica.

Método 1: usar el repositorio oficial de Docker (recomendado)

Este método mantiene Compose ligado a tu instalación de Docker, así que las actualizaciones quedan sincronizadas.

Si aún no tienes Docker Engine, primero configura el repositorio apt oficial de Docker:

# Añade la clave GPG de Docker
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Añade el repositorio
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

Ahora instala Docker Engine y el plugin de Compose juntos:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

El paquete docker-compose-plugin es el que te da docker compose como comando de la CLI. Verifica que funciona:

docker compose version

Versión de Docker Compose en una VM de Ubuntu

Eso es todo.

Método 2: instalación manual (binario independiente)

Usa este método cuando necesites una versión concreta de Compose o cuando tu entorno no permita usar el repositorio de Docker.

Empieza descargando la última versión directamente desde GitHub. Sustituye v5.0.1 por la versión que necesites:

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v5.0.1/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose

Haz el binario ejecutable:

chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Y por último, verifica la instalación:

docker compose version

Versión de Docker Compose en una VM de Ubuntu

Solo recuerda que las instalaciones manuales no se actualizan automáticamente. Si instalas un binario y te olvidas, podrías estar usando una versión obsoleta con fallos conocidos o problemas de seguridad. Si optas por este camino, acostúmbrate a revisar de vez en cuando la página de lanzamientos de Docker Compose.

Instalar Docker Compose en macOS

En macOS, no necesitas instalar Docker Compose por separado: viene incluido en Docker Desktop.

Descarga Docker Desktop desde el sitio oficial de Docker. Asegúrate de elegir la versión adecuada para tu chip: Apple Silicon (M1-M5) o Intel.

Una vez instalado, abre Docker Desktop y deja que termine de arrancar. Luego verifica que Compose está disponible con este comando:

docker compose version

Versión de Docker Compose en macOS

Listo. Compose v2 está preparado para usarse.

Opcional: instalación con Homebrew

Si prefieres gestionar tus herramientas con Homebrew y no quieres la interfaz de Docker Desktop, puedes instalar Docker y Compose con Homebrew:

brew install docker
brew install docker-compose

Si eliges esta opción, recuerda que Homebrew instala Docker Engine sin la app de Desktop. Perfecto para uso por CLI, pero perderás funciones como el panel de Docker y las actualizaciones automáticas. Para la mayoría en macOS, Docker Desktop es el camino más sencillo.

Instalar Docker Compose en Windows

Igual que en macOS, en Windows Docker Compose llega automáticamente con Docker Desktop. No hace falta una instalación aparte.

Antes de instalar Docker Desktop, necesitas tener habilitado WSL2 (Windows Subsystem for Linux 2). WSL2 permite que Docker ejecute un kernel Linux real en Windows, que es cómo funcionan los contenedores en esta plataforma. Para habilitarlo, abre PowerShell como administrador y ejecuta:

wsl --install

Reinicia el equipo cuando se te solicite. Después descarga e instala Docker Desktop desde el sitio oficial de Docker.

Durante la configuración, asegúrate de marcar la opción "Use WSL2 instead of Hyper-V". Cuando Docker Desktop esté en ejecución, verifica que Compose está disponible; puedes hacerlo en PowerShell o en tu terminal de WSL:

docker compose version

Problemas de permisos habituales

Si ves un error de "permission denied", suele deberse a una de estas dos causas:

• Docker Desktop no está en ejecución. Debe estar activo en la bandeja del sistema antes de que cualquier comando docker funcione.
• Tu usuario no está en el grupo correcto. En WSL, asegúrate de que tu usuario de Linux tiene acceso al socket de Docker. Puedes arreglarlo ejecutando tu terminal de WSL como administrador o añadiendo tu usuario al grupo docker dentro de WSL:

sudo usermod -aG docker $USER

Ahora solo cierra sesión y vuelve a iniciarla en WSL para que el cambio surta efecto.

Verificar la instalación de Docker Compose

Una vez que hayas instalado Docker Compose, ejecuta este comando para confirmar que todo funciona:

docker compose version

Deberías ver una salida similar a esta:

Versión de Compose instalada

El número exacto variará según la fecha en que leas esto, pero mientras veas v5.0.1 o superior, vas bien.

Si ves docker compose: command not found, Compose no está instalado o no está en tu PATH. Salta a la sección de resolución de problemas.

docker compose vs docker-compose

Quizá veas artículos que usan docker-compose con guion. Esta es la diferencia:

• docker-compose es el comando v1 legado. Era un binario en Python independiente, instalado aparte de Docker.

• docker compose (sin guion) es el plugin de la CLI v2, integrado directamente en la CLI de Docker.

Docker retiró el soporte de v1 en 2023, así que docker-compose ya no se mantiene. Si aún lo tienes instalado, puedes comprobar a qué versión apunta:

docker-compose --version

Si devuelve una versión 1.x.x, estás usando el binario antiguo. Desinstálalo y usa docker compose a partir de ahora. Los comandos son casi idénticos, pero v2 es más rápido y se mantiene activamente.

Actualizar Docker Compose

Cómo actualizar Compose depende de cómo lo instalaste.

En macOS y Windows, Docker Desktop se encarga de todo: abre la app, ve a Settings > Software Updates y deja que actualice si es necesario. Compose se actualiza automáticamente junto con Docker.

En Linux con el gestor de paquetes, ejecuta lo siguiente:

sudo apt-get update
sudo apt-get upgrade docker-compose-plugin

Así obtendrás la última versión desde el repositorio oficial de Docker.

Si lo instalaste manualmente, tendrás que repetir la descarga con el nuevo número de versión. Consulta la página de lanzamientos de Docker Compose para ver la última versión y, después, sustituye el binario:

curl -SL https://github.com/docker/compose/releases/download/v5.0.2/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Tras cualquier actualización, verifica que la nueva versión está activa:

docker compose version

No tiene más misterio.

Desinstalar Docker Compose

Los pasos de desinstalación dependen de cómo instalaste Compose inicialmente.

Si lo instalaste con el gestor de paquetes en Linux, elimina el plugin con este comando:

sudo apt-get remove docker-compose-plugin

Si lo instalaste manualmente, simplemente borra el binario:

rm $DOCKER_CONFIG/cli-plugins/docker-compose

Si aún tienes en el sistema el binario v1 antiguo, localízalo y elimínalo con este comando:

sudo rm /usr/local/bin/docker-compose

Después de eliminar, comprueba que se ha ido ejecutando docker compose version. Si el comando devuelve un error, la desinstalación se ha completado.

Problemas de instalación comunes

Instalar y desinstalar Docker Compose es sencillo, pero aún así puede haber contratiempos. Así puedes solucionar los problemas más habituales.

"docker compose: command not found"

Esto significa que Compose no está instalado o Docker no lo encuentra. Primero, confirma que Docker está en ejecución:

docker --version

Si Docker está bien pero falta Compose, reinstala el plugin:

sudo apt-get install docker-compose-plugin

Errores de permisos

Si ves un error de permisos al ejecutar docker compose, probablemente tu usuario no tiene acceso al socket de Docker. Añádete al grupo docker:

sudo usermod -aG docker $USER

Cierra sesión y vuelve a entrar para que el cambio se aplique. En Docker Desktop (macOS/Windows), asegúrate de que la app esté realmente en ejecución antes de probar comandos.

Incompatibilidad de versiones

Si Compose se comporta de forma extraña, comprueba qué versión estás ejecutando:

docker compose version

Si estás en una versión antigua, sigue los pasos de actualización de la sección anterior. Si tienes v1 y v2 instalados a la vez, probablemente de ahí venga la confusión.

Conflictos entre v1 y v2

Tener docker-compose (v1) y docker compose (v2) en la misma máquina puede generar conflictos. Comprueba si v1 sigue presente con este comando:

which docker-compose

Si devuelve una ruta, elimínalo:

sudo rm $(which docker-compose)

En adelante, usa docker compose (sin guion).

Problemas con el PATH

Si Docker está instalado pero no se encuentran los comandos, puede que el directorio de plugins de la CLI no esté en tu PATH. Comprueba dónde está el binario de Compose:

ls $DOCKER_CONFIG/cli-plugins/

Si está ahí pero no funciona, añade el directorio a tu PATH en ~/.bashrc o ~/.zshrc:

export PATH=$PATH:$HOME/.docker/cli-plugins

Luego recarga tu shell ejecutando esto:

source ~/.bashrc

Docker Compose v1 vs. v2

Si llevas tiempo usando Docker, seguramente hayas visto docker-compose y docker compose en artículos y vídeos. No son lo mismo.

Docker Compose v1 era un binario en Python independiente que se instalaba por separado de Docker. Usaba el comando docker-compose (con guion). Docker lo declaró obsoleto en 2023 y ya no se mantiene ni se actualiza.

Docker Compose v2 es un plugin de la CLI, escrito en Go e integrado directamente en la CLI de Docker. Se invoca con docker compose (sin guion). Viene con Docker Engine y Docker Desktop, así que en entornos modernos no hay nada extra que instalar.

La sintaxis de comandos es casi idéntica entre ambas versiones: la mayoría de los comandos de docker-compose funcionan igual con docker compose. Las principales diferencias están bajo el capó: v2 es más rápido, se integra mejor con las herramientas de Docker y se mantiene activamente.

Aquí tienes una comparación:

Tabla comparativa de Compose v1 y v2

En 2026, quédate con v2. Si tus scripts o pipelines de CI aún usan docker-compose, sustituye el guion por un espacio: ese será el único cambio necesario en la mayoría de flujos.

Conclusión

Si usas una instalación moderna de Docker, ya tienes Compose v2 instalado. No hacen falta pasos extra. En macOS y Windows, la aplicación Docker Desktop incluye Compose. Si usas Linux, lo gestiona el paquete docker-compose-plugin.

Antes de escribir o ejecutar archivos de Compose, ejecuta docker compose version para confirmar que todo está en su sitio.

Si aún usas Compose v1, es momento de cambiar. Quita el guion y elimina el binario antiguo: eso es todo. Todos tus archivos de Compose actuales funcionarán tal cual con v2.

¿Buscas más recursos sobre Docker? Apúntate a nuestro curso Introduction to Docker para aprender sobre contenedores, imágenes y mucho más.