Como instalar o Docker Compose: Linux, macOS e Windows

Você já tem o Docker rodando e domina os comandos básicos, mas está cansado de iniciar contêiner por contêiner?

O Docker Compose é a ferramenta que permite definir e executar aplicações com múltiplos contêineres a partir de um único arquivo YAML. A parte confusa é que existem duas versões por aí: o binário autônomo antigo (v1) e o plugin de CLI mais recente (v2). A maioria dos tutoriais não deixa claro qual versão está usando, então você acaba seguindo passos que não batem com o seu ambiente.

O Docker Compose v2 é um plugin que vem junto com instalações modernas do Docker, o que simplifica bastante a instalação, o uso e a verificação. O processo já não é tão manual quanto antes.

Neste artigo, vou te mostrar como instalar o Docker Compose no Linux, macOS e Windows — do jeito certo, usando a v2.

Está começando com virtualização e conteinerização? Leia nosso recente Docker para iniciantes para colocar a mão na massa.

Antes de instalar o Docker Compose

Antes de tudo, você precisa do Docker Engine na sua máquina. O Docker Compose não roda sozinho — ele depende do Docker.

Rode este comando para conferir a versão do Docker:

docker --version

Versão do Docker instalada

Se o Docker não estiver instalado, pare aqui e instale primeiro. Se já estiver, você pode verificar se o Compose já está disponível:

docker compose version

Versão do Docker Compose instalada

Se esse comando retornar um número de versão, pronto — o Compose v2 já veio junto com a sua instalação do Docker. Você pode pular direto para a seção de verificação.

Se, em vez disso, aparecer uma mensagem genérica de comando não encontrado, continue lendo.

Aqui vai a diferença que você precisa saber:

• Docker Compose v1 é o binário autônomo legado. Você o chamava com docker-compose (com hífen). Está obsoleto e não recebe mais manutenção.

• Docker Compose v2 é um plugin de CLI que acompanha o Docker moderno. Você o chama com docker compose (sem hífen).

Se você usa uma instalação recente do Docker, é quase certo que já tenha a v2. O restante do artigo assume a v2.

Instalar o Docker Compose no Linux

No Linux, você tem duas formas de obter o Docker Compose. A primeira usa o repositório oficial do Docker — é o caminho recomendado. A segunda é uma instalação manual, útil quando você não pode usar um gerenciador de pacotes ou precisa de uma versão específica.

Método 1: usando o repositório oficial do Docker (recomendado)

Esse método mantém o Compose atrelado à sua instalação do Docker, então as atualizações ficam em sincronia.

Se você ainda não tem o Docker Engine instalado, primeiro configure o repositório oficial apt do Docker:

# Adicionar a chave GPG do 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

# Adicionar o repositório
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

Agora instale o Docker Engine e o plugin do Compose juntos:

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

O pacote docker-compose-plugin é o que disponibiliza o docker compose como comando de CLI. Verifique se está funcionando:

docker compose version

Versão do Docker Compose em uma VM Ubuntu

É isso.

Método 2: instalação manual (binário autônomo)

Use este método quando você precisa de uma versão específica do Compose ou quando seu ambiente não suporta o repositório do Docker.

Comece baixando a versão mais recente diretamente do GitHub. Substitua v5.0.1 pela versão de que você precisa:

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

Torne o binário executável:

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

E por fim, verifique a instalação:

docker compose version

Versão do Docker Compose em uma VM Ubuntu

A única coisa para lembrar é que instalações manuais não atualizam automaticamente. Se você instalar um binário e esquecer dele, pode acabar usando uma versão desatualizada com bugs conhecidos ou problemas de segurança. Se optar por esse caminho, crie o hábito de checar a página de releases do Docker Compose de tempos em tempos.

Instalar o Docker Compose no macOS

No macOS, você não precisa instalar o Docker Compose separadamente — ele vem incluído no Docker Desktop.

Baixe o Docker Desktop no site oficial da Docker. Certifique-se de escolher a versão correta para o seu chip — Apple Silicon (M1–M5) ou Intel.

Depois de instalar, abra o Docker Desktop e aguarde ele iniciar completamente. Em seguida, verifique se o Compose está disponível rodando este comando:

docker compose version

Versão do Docker Compose no macOS

Pronto. O Compose v2 está pronto para uso.

Opcional: instalar via Homebrew

Se você prefere gerenciar ferramentas com o Homebrew e não quer a interface do Docker Desktop, pode instalar o Docker e o Compose por lá:

brew install docker
brew install docker-compose

Se optar por esse caminho, lembre-se de que o Homebrew instala o Docker Engine sem o app Desktop. Isso funciona bem via CLI, mas você não terá recursos como o Docker Dashboard e atualizações automáticas. Para a maioria dos usuários de macOS, o Docker Desktop é o caminho mais simples.

Instalar o Docker Compose no Windows

Assim como no macOS, o Windows recebe o Docker Compose automaticamente via Docker Desktop. Não é necessário instalar separadamente.

Antes de instalar o Docker Desktop, você precisa ativar o WSL2 (Windows Subsystem for Linux 2). O WSL2 permite que o Docker rode um kernel Linux real no Windows, que é como os contêineres funcionam nessa plataforma. Para ativar, abra o PowerShell como Administrador e rode:

wsl --install

Reinicie a máquina quando for solicitado. Depois, baixe e instale o Docker Desktop no site oficial da Docker.

Durante a instalação, garanta que a opção "Use WSL2 instead of Hyper-V" esteja marcada. Quando o Docker Desktop estiver rodando, verifique se o Compose está disponível — você pode fazer isso tanto no PowerShell quanto no terminal do WSL:

docker compose version

Problemas comuns de permissão

Se você encontrar um erro de "permission denied", geralmente é um destes dois casos:

• O Docker Desktop não está rodando. Ele precisa estar ativo na bandeja do sistema antes de qualquer comando docker funcionar.
• Seu usuário não está no grupo correto. No WSL, garanta que seu usuário Linux tenha acesso ao socket do Docker. Você pode corrigir isso executando o terminal do WSL como Administrador ou adicionando seu usuário ao grupo docker dentro do WSL:

sudo usermod -aG docker $USER

Agora é só sair e entrar novamente no WSL para a mudança surtir efeito.

Verificar a instalação do Docker Compose

Depois de instalar o Docker Compose, rode este comando para confirmar que está tudo certo:

docker compose version

Você deve ver uma saída como esta:

Versão do Compose instalada

O número exato da versão vai variar conforme a data em que você lê, mas se aparecer v5.0.1 ou mais recente, você está pronto para começar.

Se aparecer docker compose: command not found, o Compose não está instalado ou não está no seu PATH. Pule para a seção de troubleshooting abaixo.

docker compose vs docker-compose

Você pode notar que alguns artigos usam docker-compose com hífen. Eis a diferença:

• docker-compose é o comando legado da v1. Era um binário em Python instalado separadamente do Docker.

• docker compose (sem hífen) é o plugin de CLI da v2, integrado diretamente ao Docker CLI.

A Docker descontinuou a v1 em 2023, então o docker-compose não é mais mantido. Se você ainda o tem instalado, pode verificar para qual versão ele aponta:

docker-compose --version

Se retornar uma versão 1.x.x, você está rodando o binário antigo. Desinstale-o e passe a usar docker compose daqui para frente. Os comandos são quase idênticos, mas a v2 é mais rápida e mantida ativamente.

Atualizar o Docker Compose

Como atualizar o Compose depende de como você o instalou.

No macOS e no Windows, o Docker Desktop cuida de tudo. Basta abrir o app, ir em Settings > Software Updates e deixar ele atualizar, se necessário. O Compose é atualizado automaticamente junto com o Docker.

No Linux com gerenciador de pacotes, rode:

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

Isso baixa a versão mais recente do repositório oficial da Docker.

Se você instalou manualmente, será preciso repetir o passo do download com o novo número de versão. Consulte a página de releases do Docker Compose para a versão mais recente e então substitua o binário:

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

Após qualquer atualização, verifique se a nova versão está ativa:

docker compose version

Só isso.

Desinstalar o Docker Compose

Os passos de desinstalação dependem de como você instalou o Compose.

Se você instalou via gerenciador de pacotes no Linux, remova o plugin com este comando:

sudo apt-get remove docker-compose-plugin

Se você instalou manualmente, basta apagar o binário:

rm $DOCKER_CONFIG/cli-plugins/docker-compose

Se você ainda tem o binário autônomo v1 no sistema, localize e remova com este comando:

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

Depois de remover, confirme que saiu do ar rodando docker compose version. Se o comando retornar erro, a desinstalação funcionou.

Problemas comuns de instalação

Instalar e desinstalar o Docker Compose é simples, mas ainda assim algumas coisas podem dar errado. Veja como resolver possíveis problemas.

"docker compose: command not found"

Isso significa que o Compose não está instalado ou o Docker não consegue encontrá-lo. Primeiro, confirme que o próprio Docker está rodando:

docker --version

Se o Docker estiver ok, mas o Compose estiver faltando, reinstale o plugin:

sudo apt-get install docker-compose-plugin

Erros de permissão negada

Se você vir um erro de permissão ao executar docker compose, provavelmente seu usuário não tem acesso ao socket do Docker. Adicione-se ao grupo docker:

sudo usermod -aG docker $USER

Saia e entre novamente para a mudança valer. No Docker Desktop (macOS/Windows), garanta que o app está realmente rodando antes de tentar qualquer comando.

Incompatibilidade de versões

Se o Compose estiver se comportando de forma estranha, confira qual versão você está usando:

docker compose version

Se for uma versão antiga, siga os passos de atualização descritos antes. Se você tem v1 e v2 instaladas, isso provavelmente é a fonte da confusão.

Conflitos entre v1 e v2

Ter docker-compose (v1) e docker compose (v2) na mesma máquina pode causar conflitos. Verifique se a v1 ainda está presente com este comando:

which docker-compose

Se retornar um caminho, remova:

sudo rm $(which docker-compose)

Use docker compose (sem hífen) daqui para frente.

Problemas de PATH

Se o Docker estiver instalado, mas os comandos não forem encontrados, o diretório de plugins da CLI pode não estar no seu PATH. Confira onde está o binário do Compose:

ls $DOCKER_CONFIG/cli-plugins/

Se ele estiver lá, mas ainda não funcionar, adicione o diretório ao seu PATH no ~/.bashrc ou ~/.zshrc:

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

Depois recarregue seu shell rodando:

source ~/.bashrc

Docker Compose v1 vs. v2

Se você usa Docker há algum tempo, provavelmente já viu docker-compose e docker compose em artigos e vídeos. Eles não são a mesma coisa.

Docker Compose v1 era um binário em Python instalado separadamente do Docker. Usava o comando docker-compose (com hífen). A Docker o descontinuou em 2023 — não recebe mais manutenção nem atualizações.

Docker Compose v2 é um plugin de CLI em Go, integrado diretamente ao Docker CLI. Você o chama com docker compose (sem hífen). Ele vem com o Docker Engine e o Docker Desktop, então não há nada extra para instalar em setups modernos.

A sintaxe de comandos é quase idêntica entre as duas versões — a maioria dos comandos docker-compose funciona do mesmo jeito com docker compose. As principais diferenças estão por baixo dos panos: a v2 é mais rápida, melhor integrada às ferramentas do Docker e mantida ativamente.

Aqui vai uma comparação:

Tabela de comparação entre Compose v1 e v2

Em 2026, fique com a v2. Se seus scripts ou pipelines de CI ainda usam docker-compose, troque o hífen por um espaço — essa é a única mudança necessária para a maioria dos fluxos.

Conclusão

Se você usa uma instalação moderna do Docker, o Compose v2 já está instalado. Não há passos extras. No macOS e no Windows, o aplicativo Docker Desktop já vem com o Compose. No Linux, ele é fornecido pelo pacote docker-compose-plugin.

Antes de começar a escrever ou rodar arquivos do Compose, execute docker compose version para confirmar que está tudo no lugar.

Se você ainda usa o Compose v1, agora é a hora de migrar. Tire o hífen e remova o binário antigo — é só isso. Todos os seus arquivos Compose existentes funcionarão como estão na v2.

Quer mais conteúdos sobre Docker? Inscreva-se no nosso curso Introduction to Docker para aprender sobre contêineres, imagens e muito mais.