Come installare Docker Compose: Linux, macOS e Windows

Hai Docker in esecuzione e te la cavi con i comandi di base, ma sei stanco di avviare i container uno per uno?

Docker Compose è uno strumento che ti permette di definire ed eseguire applicazioni multi-container da un unico file YAML. La parte confusa è che circolano due versioni: il vecchio binario standalone (v1) e il nuovo plugin della CLI (v2). Molti articoli di installazione non specificano quale usano, quindi finisci per seguire passaggi che non corrispondono alla tua configurazione.

Docker Compose v2 è un plugin incluso nelle installazioni moderne di Docker, il che semplifica davvero il modo in cui lo installi, lo esegui e lo verifichi. Il processo non è più così manuale come un tempo.

In questo articolo ti mostrerò come installare Docker Compose su Linux, macOS e Windows - nel modo giusto, usando la v2.

Sei alle prime armi con i concetti di virtualizzazione e containerizzazione? Leggi il nostro recente articolo Docker per principianti per fare pratica.

Prima di installare Docker Compose

Prima di tutto, ti serve Docker Engine sulla macchina. Docker Compose non funziona da solo: ha bisogno di Docker per operare.

Esegui questo comando per controllare la versione di Docker:

docker --version

Versione di Docker installata

Se Docker non è installato, fermati qui e installalo prima. Se è installato, puoi verificare se Compose è già disponibile:

docker compose version

Versione di Docker Compose installata

Se restituisce un numero di versione, hai finito: Compose v2 è già incluso nella tua installazione di Docker. Puoi passare direttamente alla sezione di verifica.

Se invece restituisce un generico messaggio di comando non trovato, continua a leggere.

Ecco la distinzione chiave da conoscere:

• Docker Compose v1 è il vecchio binario standalone. Lo richiamavi con docker-compose (con il trattino). È deprecato e non più mantenuto.

• Docker Compose v2 è un plugin della CLI fornito con le versioni moderne di Docker. Lo richiami con docker compose (senza trattino).

Se hai un'installazione recente di Docker, con ogni probabilità hai già la v2. Il resto di questo articolo presuppone la v2.

Installare Docker Compose su Linux

Su Linux hai due modi per ottenere Docker Compose. Il primo usa il repository ufficiale di Docker: è il percorso consigliato. Il secondo è un'installazione manuale, utile quando non puoi usare un gestore pacchetti o ti serve una versione specifica.

Metodo 1: usare il repository ufficiale di Docker (consigliato)

Questo metodo mantiene Compose allineato alla tua installazione di Docker, così gli aggiornamenti restano sincronizzati.

Se non hai ancora installato Docker Engine, configura prima il repository apt ufficiale di Docker:

# Add Docker's GPG key
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

# Add the repository
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

Ora installa insieme Docker Engine e il plugin Compose:

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

Il pacchetto docker-compose-plugin è ciò che ti fornisce docker compose come comando della CLI. Verifica che funzioni:

docker compose version

Versione di Docker Compose su VM Ubuntu

Tutto qui.

Metodo 2: installazione manuale (binario standalone)

Usa questo metodo quando ti serve una versione specifica di Compose o quando il tuo ambiente non supporta il repository di Docker.

Inizia scaricando l'ultima release direttamente da GitHub. Sostituisci v5.0.1 con la versione di cui hai bisogno:

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

Rendi il binario eseguibile:

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

E infine, verifica l'installazione:

docker compose version

Versione di Docker Compose su VM Ubuntu

L'unica cosa da ricordare è che le installazioni manuali non si aggiornano automaticamente. Se installi un binario e te ne dimentichi, potresti ritrovarti a eseguire una versione obsoleta con bug noti o problemi di sicurezza. Se scegli questa strada, abituati a controllare periodicamente la pagina delle release di Docker Compose.

Installare Docker Compose su macOS

Su macOS non serve installare Docker Compose separatamente: è incluso in Docker Desktop.

Scarica Docker Desktop dal sito ufficiale di Docker. Assicurati di scegliere la versione giusta per il tuo chip: Apple Silicon (M1-M5) o Intel.

Una volta installato, apri Docker Desktop e lascialo completare l'avvio. Poi verifica che Compose sia disponibile eseguendo questo comando:

docker compose version

Versione di Docker Compose su macOS

Tutto qui. Compose v2 è pronto all'uso.

Opzionale: installazione tramite Homebrew

Se preferisci gestire gli strumenti con Homebrew e non vuoi la GUI completa di Docker Desktop, puoi installare Docker e Compose tramite Homebrew:

brew install docker
brew install docker-compose

Se scegli questa strada, ricorda che Homebrew installa Docker Engine senza l'app Desktop. Va benissimo per l'uso da CLI, ma ti mancheranno funzionalità come la Docker Dashboard e gli aggiornamenti automatici. Per la maggior parte degli utenti macOS, Docker Desktop è la via più semplice.

Installare Docker Compose su Windows

Come su macOS, anche su Windows Docker Compose arriva automaticamente con Docker Desktop. Non serve un'installazione separata.

Prima di installare Docker Desktop, devi abilitare WSL2 (Windows Subsystem for Linux 2). WSL2 consente a Docker di eseguire un vero kernel Linux su Windows, che è il modo in cui i container funzionano su questa piattaforma. Per abilitarlo, apri PowerShell come Amministratore ed esegui:

wsl --install

Riavvia la macchina quando richiesto. Quindi scarica e installa Docker Desktop dal sito ufficiale di Docker.

Durante la configurazione, assicurati che l'opzione "Use WSL2 instead of Hyper-V" sia selezionata. Una volta che Docker Desktop è in esecuzione, verifica che Compose sia disponibile: puoi farlo sia in PowerShell che nel tuo terminale WSL:

docker compose version

Problemi comuni di permessi

Se incontri un errore "permission denied", di solito è per uno di questi due motivi:

• Docker Desktop non è in esecuzione. Deve essere attivo nell'area di notifica prima che qualsiasi comando docker funzioni.
• Il tuo utente non è nel gruppo corretto. In WSL, assicurati che l'utente Linux abbia accesso al socket di Docker. Puoi risolvere eseguendo il terminale WSL come Amministratore o aggiungendo il tuo utente al gruppo docker all'interno di WSL:

sudo usermod -aG docker $USER

Ora disconnettiti e rientra in WSL perché la modifica abbia effetto.

Verificare l'installazione di Docker Compose

Una volta installato Docker Compose, esegui questo comando per confermare che tutto funzioni:

docker compose version

Dovresti vedere un output simile a questo:

Versione di Compose installata

Il numero di versione esatto varierà a seconda del momento in cui leggi, ma finché vedi v5.0.1 o superiore, sei a posto.

Se vedi docker compose: command not found, Compose non è installato o non è nel tuo PATH. Vai alla sezione di troubleshooting qui sotto.

docker compose vs docker-compose

Potresti notare che alcuni articoli online usano docker-compose con il trattino. Ecco la differenza:

• docker-compose è il comando legacy v1. Era un binario Python standalone installato separatamente da Docker.

• docker compose (senza trattino) è il plugin CLI v2, integrato direttamente nella CLI di Docker.

Docker ha abbandonato il supporto per la v1 nel 2023, quindi docker-compose non è più mantenuto. Se lo hai ancora installato, puoi controllare a quale versione punta:

docker-compose --version

Se restituisce una versione 1.x.x, stai eseguendo il vecchio binario. Disinstallalo e usa docker compose in futuro. I comandi sono quasi identici, ma la v2 è più veloce e attivamente mantenuta.

Aggiornare Docker Compose

Come aggiornare Compose dipende da come lo hai installato.

Su macOS e Windows, Docker Desktop gestisce tutto per te: apri l'app, vai su Settings > Software Updates e lascia che aggiorni se necessario. Compose si aggiorna automaticamente insieme a Docker.

Su Linux con il gestore pacchetti, esegui quanto segue:

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

Questo scarica l'ultima versione dal repository ufficiale di Docker.

Se hai installato manualmente, dovrai ripetere il passaggio di download con il nuovo numero di versione. Controlla la pagina delle release di Docker Compose per l'ultima versione, poi sostituisci il 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

Dopo qualsiasi aggiornamento, verifica che la nuova versione sia attiva:

docker compose version

Nient'altro da fare.

Disinstallare Docker Compose

I passaggi di disinstallazione dipendono da come hai installato Compose in origine.

Se lo hai installato tramite gestore pacchetti su Linux, rimuovi il plugin con questo comando:

sudo apt-get remove docker-compose-plugin

Se lo hai installato manualmente, elimina semplicemente il binario:

rm $DOCKER_CONFIG/cli-plugins/docker-compose

Se hai ancora sul sistema il vecchio binario v1 standalone, trovalo e rimuovilo con questo comando:

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

Dopo la rimozione, fai un doppio controllo eseguendo docker compose version. Se il comando restituisce un errore, la disinstallazione è riuscita.

Problemi comuni di installazione

Installare e disinstallare Docker Compose è semplice, ma ci sono comunque alcune cose che possono andare storte. Ecco come risolvere i possibili problemi in cui potresti imbatterti.

"docker compose: command not found"

Questo significa che Compose non è installato oppure Docker non riesce a trovarlo. Per prima cosa, conferma che Docker sia in esecuzione:

docker --version

Se Docker è a posto ma Compose manca, reinstalla semplicemente il plugin:

sudo apt-get install docker-compose-plugin

Errori di permessi negati

Se vedi un errore di permesso negato quando esegui docker compose, probabilmente il tuo utente non ha accesso al socket di Docker. Aggiungiti al gruppo docker:

sudo usermod -aG docker $USER

Disconnettiti e rientra perché la modifica abbia effetto. Su Docker Desktop (macOS/Windows), assicurati che l'app sia effettivamente in esecuzione prima di provare qualsiasi comando.

Versioni non allineate

Se Compose si comporta in modo inatteso, controlla quale versione stai effettivamente eseguendo:

docker compose version

Se stai usando una versione vecchia, segui i passaggi di aggiornamento descritti nella sezione precedente. Se hai sia v1 sia v2 installate, è probabilmente questa la fonte di confusione.

Conflitti tra v1 e v2

Avere sulla stessa macchina sia docker-compose (v1) sia docker compose (v2) può causare conflitti. Verifica se la v1 è ancora presente con questo comando:

which docker-compose

Se restituisce un percorso, rimuovila:

sudo rm $(which docker-compose)

Usa docker compose (senza trattino) d'ora in poi.

Problemi di PATH

Se Docker è installato ma i comandi non vengono trovati, è possibile che la directory dei plugin CLI non sia nel tuo PATH. Controlla dove si trova il binario di Compose:

ls $DOCKER_CONFIG/cli-plugins/

Se è lì ma non funziona, aggiungi la directory al tuo PATH in ~/.bashrc o in ~/.zshrc:

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

Poi ricarica la shell eseguendo questo:

source ~/.bashrc

Docker Compose v1 vs. v2

Se usi Docker da un po', probabilmente hai visto sia docker-compose sia docker compose in articoli e video online. Non sono la stessa cosa.

Docker Compose v1 era un binario Python standalone che installavi separatamente da Docker. Usava il comando docker-compose (con trattino). Docker lo ha deprecato nel 2023 e non è più mantenuto o aggiornato.

Docker Compose v2 è un plugin CLI basato su Go integrato direttamente nella CLI di Docker. Lo richiami con docker compose (senza trattino). È incluso in Docker Engine e Docker Desktop, quindi nelle configurazioni moderne non c'è nulla di extra da installare.

La sintassi dei comandi è quasi identica tra le due versioni: la maggior parte dei comandi docker-compose funziona allo stesso modo con docker compose. Le principali differenze sono sotto il cofano: la v2 è più veloce, meglio integrata con gli strumenti di Docker e attivamente mantenuta.

Ecco un confronto:

Tabella di confronto tra Compose v1 e v2

Nel 2026, resta su v2. Se i tuoi script o pipeline CI usano ancora docker-compose, sostituisci il trattino con uno spazio: per la maggior parte dei workflow è l'unico cambiamento necessario.

Conclusione

Se usi una versione moderna di Docker, hai già Compose v2 installato. Non servono passaggi extra. Su macOS e Windows, l'applicazione Docker Desktop include Compose. Se usi Linux, è gestito dal pacchetto docker-compose-plugin.

Prima di iniziare a scrivere o eseguire file Compose, esegui docker compose version per confermare che sia tutto a posto.

Se stai ancora usando Compose v1, è il momento di passare oltre. Elimina il trattino e rimuovi il vecchio binario: è tutto ciò che devi fare. Tutti i tuoi file Compose esistenti funzioneranno così come sono con la v2.

Cerchi altre risorse su Docker? Iscriviti al nostro corso Introduzione a Docker per imparare a conoscere container, immagini e altro.