Alternar tema

Como instalar o Docker em 2025: do permission denied ao primeiro contêiner

Easton editorial illustration: service mesh rail yard

Foi a terceira vez que instalei o Docker: na primeira, o WSL 2 deu erro; na segunda, o daemon simplesmente não iniciava. Quando finalmente consegui instalar, docker ps respondeu com permission denied.

Instalar o Docker deveria ser simples: baixar o instalador, abrir e avançar. Na prática, o Windows exige atenção ao WSL 2 e ao Hyper-V; no Mac, é preciso escolher entre as versões para Intel e Apple Silicon; no Linux, aparecem dependências e permissões de grupo. Cada plataforma tem suas próprias armadilhas.

Este guia reúne o que aprendi ao resolver esses problemas. Listei mais de dez erros frequentes no Windows, macOS e Linux, com soluções atualizadas para 2025 — muitos tutoriais de 2020 a 2022 já ficaram defasados. Encontre abaixo a sua plataforma e o erro que apareceu.

Problemas comuns no Windows

Instalar o Docker no Windows costuma significar lidar com WSL 2 e Hyper-V. Hoje, o Docker Desktop exige o backend WSL 2; se a versão do sistema estiver incorreta ou a virtualização estiver desativada, surgem mensagens de erro pouco claras.

Problema 1: instalação incompleta do WSL 2

Este é o erro mais frequente entre usuários do Windows. Você abre o Docker Desktop e vê a mensagem “WSL 2 installation is incomplete”, sem mais explicações.

A mensagem é parecida com esta:

Docker Desktop requires WSL 2 backend
WSL 2 installation is incomplete

Há três causas principais: a versão do Windows é antiga demais (inferior a 10.0.19041), o recurso WSL não está ativo ou a virtualização foi desativada no BIOS.

Como corrigir:

Primeiro, verifique a versão do Windows. Pressione Win+R, digite winver e confira o número. Você precisa de, no mínimo, Windows 10 22H2 (build 19045) ou Windows 11 23H2 (build 22631+). Se a versão for anterior, atualize o sistema antes.

Depois, ative o WSL. Acesse Painel de Controle → Programas e Recursos → Ativar ou desativar recursos do Windows. Marque “Subsistema do Windows para Linux” e “Plataforma de Máquina Virtual”. Ao terminar, reinicie o computador; esta etapa é obrigatória.

Após reiniciar, abra o PowerShell como administrador e atualize o WSL:

wsl --update
wsl --set-default-version 2

A primeira linha instala a versão mais recente do WSL — você precisa da 2.1.5 ou posterior — e a segunda define o WSL 2 como padrão.

Se ainda não funcionar, entre no BIOS. Reinicie o computador, pressione Del ou F2, conforme o fabricante da placa-mãe, e procure Virtualization Technology ou Intel VT-x/AMD-V. Defina a opção como Enabled. Intel chama o recurso de VT-x e AMD, de AMD-V; a função é a mesma.

Problema 2: conflito com Hyper-V

Às vezes, aparece um erro como este:

HCS_E_HYPERV_NOT_INSTALLED
Docker Desktop - Unexpected WSL error

Isso indica que o Hyper-V não está instalado ou está em conflito com outro software de virtualização. O Docker Desktop depende do Hyper-V ou do WSL 2, e a presença simultânea de VMware ou VirtualBox pode causar problemas.

Como corrigir:

Se o Hyper-V estiver desativado, abra os Recursos do Windows, localize “Hyper-V”, marque todos os subitens e reinicie. O Windows Home não oferece Hyper-V, portanto você terá de usar o backend WSL 2.

Se você também usa VMware ou VirtualBox, talvez seja necessário escolher um deles. Desde a versão 4.x, o Docker Desktop prioriza o backend WSL 2, que tende a oferecer melhor compatibilidade. Em teoria, VMware Workstation 15.5 ou posterior pode coexistir com Hyper-V, mas, na minha experiência, ainda surgem pequenos problemas.

A opção mais simples é separar os ambientes: Docker Desktop com WSL 2 para desenvolvimento e VMware ou VirtualBox para produção ou máquinas virtuais de teste.

Problema 3: permissão insuficiente para instalar

Esse erro costuma aparecer durante a instalação:

Installation Failed
Component CommunityInstaller.EnableFeaturesAction failed

A causa é simples: o instalador não foi executado como administrador ou foi bloqueado pelo antivírus.

Como corrigir:

Clique com o botão direito no instalador do Docker Desktop e selecione “Executar como administrador”. Se o firewall ou o antivírus pedir autorização durante a instalação, permita o acesso.

Outro detalhe fácil de esquecer é o espaço na unidade C. O Docker Desktop precisa de pelo menos 10 GB livres, e as imagens ocuparão ainda mais. É possível mudar o local dos dados depois da instalação, mas esse é outro assunto.

Em computadores corporativos, políticas de grupo também podem bloquear a instalação. Nesse caso, peça permissão ao setor de TI ou instale o Docker Engine dentro do subsistema Linux, sabendo que essa alternativa não inclui interface gráfica.

Problemas comuns no Mac

No Mac, a instalação costuma ser mais tranquila. Porém, desde a chegada dos chips M1 e M2, surgiu uma nova armadilha: instalar a versão Intel em um Mac com chip Apple, ou o contrário.

Problema 1: compatibilidade com chips M1/M2

Os sintomas são claros: o ícone do Docker Desktop não aparece na barra de menus ou fica para sempre em “Docker Desktop is starting…”. Ao executar um comando docker no Terminal, você recebe:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Provavelmente, o instalador não corresponde ao chip. O site do Docker oferece duas versões: “Mac with Apple chip” e “Mac with Intel chip”. A versão errada não inicia corretamente.

Como corrigir:

Primeiro, confirme o chip do Mac. Abra o menu Apple → Sobre Este Mac e veja o campo “Chip”. Se aparecer “Apple M1” ou “Apple M2”, use a versão Apple Silicon; se aparecer “Intel Core”, use a versão Intel.

Caso tenha instalado a versão errada, desinstale-a completamente. Abra o Terminal e execute:

# Desinstalar o Docker Desktop
/Applications/Docker.app/Contents/MacOS/uninstall

# Excluir os arquivos de configuração restantes
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker

Esses comandos apagam o Docker e todos os dados em cache. Em seguida, baixe do site a versão adequada ao chip e instale novamente.

Há mais um detalhe: Macs M1/M2 precisam do Rosetta 2 para executar algumas imagens x86. Se ele não estiver instalado, execute:

softwareupdate --install-rosetta

Depois da instalação, reinicie o Docker Desktop.

Problema 2: daemon travado na inicialização

Em alguns casos, o Docker Desktop abre e o ícone aparece, mas o estado permanece em “Starting…”. O Monitor de Atividade mostra processos do Docker em execução, porém o programa não pode ser usado.

Geralmente, isso é causado por uma configuração corrompida ou por outro processo que ocupa uma porta do Docker.

Como corrigir:

Primeiro, redefina o Docker Desktop. Clique no ícone do Docker na barra de menus, selecione Troubleshoot e depois “Reset to factory defaults”. Isso remove todos os contêineres, imagens e configurações. Faça backup de imagens importantes antes.

Se a redefinição não resolver, procure conflitos nas portas 2375 e 2376, usadas por padrão pelo Docker:

# Verificar o uso das portas
lsof -i :2375
lsof -i :2376

# Se houver saída, anote o PID e encerre o processo
kill -9 <PID>

Depois de encerrar o processo em conflito, reinicie o Docker Desktop.

Outra opção, mais radical, é excluir os arquivos da máquina virtual do Docker:

rm -rf ~/Library/Containers/com.docker.docker/Data/vms

Isso força o Docker a reconstruir o ambiente da máquina virtual. Ao reiniciar o Docker Desktop, uma nova VM será criada automaticamente.

Problema 3: permissão negada ao montar arquivos

Ao montar um diretório local em um contêiner, você pode receber:

Error response from daemon: Mounts denied:
The path /Users/yourname/project is not shared from the host and is not known to Docker.

O Docker não tem permissão para acessar o diretório que você quer montar. O macOS aplica controles de privacidade rigorosos, e o Docker só pode acessar determinados caminhos por padrão.

Como corrigir:

Abra as configurações do Docker Desktop → Resources → File Sharing e clique no sinal de mais para adicionar o diretório. Em geral, /Users, /Volumes, /private e /tmp já são permitidos, mas talvez seja preciso adicionar um subdiretório específico.

Se ainda não funcionar, abra Ajustes do Sistema → Privacidade e Segurança → Acesso Total ao Disco e confirme que o Docker Desktop está marcado. O macOS 14.3 ou posterior é mais rigoroso com permissões, portanto não ignore esta etapa.

Se o diretório estiver em um disco externo ou compartilhamento de rede, talvez seja necessária uma configuração separada no Docker. Discos externos normalmente ficam em /Volumes; adicione o caminho correspondente.

Problemas comuns no Linux

Em teoria, instalar o Docker no Linux deveria ser mais simples, já que ele foi criado para essa plataforma. Na prática, ainda há armadilhas, principalmente em permissões e dependências.

Problema 1: Permission Denied, o erro mais frequente

Quase todo iniciante no Linux encontra esse erro. Depois de instalar o Docker, você executa docker ps e recebe:

docker: Got permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/...":
dial unix /var/run/docker.sock: connect: permission denied.

A mensagem é longa, mas a causa é direta: o daemon do Docker é executado como root, e o usuário atual não tem permissão para acessar o socket /var/run/docker.sock.

Como corrigir:

Adicione o usuário ao grupo docker:

sudo usermod -aG docker $USER

Esse comando adiciona o usuário atual ($USER) ao grupo docker (-aG docker). Mas ainda falta uma etapa.

A alteração de grupo não entra em vigor imediatamente. Atualize os grupos ou entre novamente na sessão:

newgrp docker

Você também pode fazer logout e login outra vez. Muita gente altera o grupo, não reinicia a sessão e conclui que a solução não funcionou.

Confirme a alteração:

groups

Se a saída contiver docker, está correto. Execute docker ps novamente; o erro deve desaparecer.

Atenção: existe uma implicação de segurança. Adicionar um usuário ao grupo docker equivale a conceder privilégios de root, porque o Docker pode acessar todo o sistema de arquivos. Em uma máquina pessoal de desenvolvimento isso costuma ser aceitável, mas exige cuidado em servidores de produção.

Se ainda não funcionar, confira as permissões do socket:

ls -l /var/run/docker.sock

O resultado esperado é srw-rw---- 1 root docker. Se for diferente, você pode alterar manualmente:

sudo chmod 666 /var/run/docker.sock

Essa é apenas uma solução temporária e deixa de valer após a reinicialização. O correto continua sendo adicionar o usuário ao grupo.

Problema 2: dependências ausentes em Ubuntu/Debian

Este erro costuma aparecer durante a instalação:

docker-desktop : Depends: docker-ce-cli but it is not installable
The following packages have unmet dependencies:
 docker-desktop : Depends: pass but it is not installable
                  Depends: uidmap but it is not installable
                  Depends: gnome-terminal but it is not installable

Embora pareça que faltam muitos pacotes, a causa principal é a ausência do repositório oficial do Docker. O repositório apt padrão do sistema não inclui o Docker ou oferece uma versão antiga.

Como corrigir no Ubuntu:

Primeiro, remova versões antigas, se existirem:

sudo apt-get remove docker docker-engine docker.io containerd runc

Em seguida, configure o repositório oficial do Docker. Esta etapa é essencial e muitos tutoriais a omitem ou resumem demais:

# Atualizar o índice de pacotes do apt
sudo apt-get update

# Instalar as dependências necessárias
sudo apt-get install ca-certificates curl gnupg lsb-release

# Adicionar a chave GPG oficial do Docker
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Configurar o repositório do Docker
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Na última linha, $(lsb_release -cs) detecta automaticamente o codinome da versão do Ubuntu, como jammy ou focal. No Linux Mint, isso pode causar problemas: o Mint é baseado no Ubuntu, mas usa outro número de versão. Consulte /etc/os-release e use o valor de UBUNTU_CODENAME, não o codinome do próprio Mint.

Depois de adicionar o repositório, atualize e instale:

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

Agora os pacotes serão baixados do repositório oficial do Docker e as dependências poderão ser resolvidas. Ao terminar, execute docker --version.

Problema 3: falha ao iniciar o daemon

Depois de instalar o Docker, um comando pode retornar:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

O problema se parece com o do Mac, mas no Linux o daemon é gerenciado pelo systemd, portanto o diagnóstico é diferente.

Como corrigir:

Primeiro, verifique o estado do serviço Docker:

sudo systemctl status docker

Se aparecer inactive (dead) ou failed, o serviço não iniciou ou falhou na inicialização. Tente iniciá-lo manualmente:

sudo systemctl start docker
sudo systemctl enable docker  # Ativar na inicialização do sistema

Se a inicialização falhar, veja os logs detalhados:

sudo journalctl -u docker.service -n 50

O comando mostra as 50 linhas mais recentes e geralmente revela a causa específica.

Subproblemas comuns:

Conflito com SELinux em CentOS/RHEL:
Se os logs mencionarem o SELinux, desative a imposição temporariamente para testar:

sudo setenforce Permissive

Essa alteração é temporária e será revertida após reiniciar. Para desativar permanentemente, seria necessário editar /etc/selinux/config, mas isso não é recomendado em produção; prefira configurar uma política adequada.

Erro de sintaxe no arquivo de configuração:
Se você alterou /etc/docker/daemon.json, verifique a sintaxe JSON. Uma vírgula ausente ou uma aspa extra impede o serviço de iniciar. Use jsonlint ou uma ferramenta online para validar.

Bloqueio pelo firewall:
Algumas distribuições Linux adotam regras de firewall rigorosas que podem bloquear o Docker. Desative o firewall temporariamente para testar:

sudo systemctl stop firewalld  # CentOS/RHEL
sudo ufw disable              # Ubuntu

Se o Docker iniciar com o firewall desativado, configure regras que permitam seu funcionamento.

Problema 4: conflito de porta

Este erro é menos comum, mas pode ser trabalhoso:

Error starting daemon: error initializing graphdriver: driver not supported
bind: address already in use

Em geral, a porta padrão do Docker, 2375 ou 2376, está ocupada por outro processo, ou há conflito ao configurar acesso remoto.

Como corrigir:

Verifique o uso das portas:

sudo netstat -tulnp | grep 2375
sudo netstat -tulnp | grep 2376

Se houver saída, anote o PID e encerre o processo:

sudo kill -9 <PID>

Se precisar de acesso remoto ao Docker — o que não é recomendado por motivos de segurança — você pode alterar a porta de escuta. Edite /etc/docker/daemon.json:

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2376"]
}

Nesse exemplo, o Docker escuta somente o endereço de loopback 127.0.0.1, que é mais seguro. Para escutar todas as interfaces (0.0.0.0), configure TLS; nunca exponha essa porta sem criptografia.

Depois de alterar a configuração, reinicie o Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Há uma armadilha: configurar hosts ao mesmo tempo em daemon.json e no arquivo de serviço do systemd causa conflito. Verifique /lib/systemd/system/docker.service; se a linha ExecStart tiver um parâmetro -H, remova-o e mantenha a configuração apenas em daemon.json.

Processo completo de instalação do Docker nas três plataformas

Etapas da instalação à verificação, com problemas comuns e soluções para Windows, Mac e Linux

Estimated time: PT30M

  1. 1

    Step 1: Instalação no Windows

    Verifique a versão do Windows:
  2. 2

    Step 2: Instalação no Mac

    Confirme o tipo de chip do Mac:
  3. 3

    Step 3: Instalação no Linux

    Remova versões antigas:
  4. 4

    Step 4: Resolver Permission Denied no Linux

    Adicione o usuário ao grupo docker:
  5. 5

    Step 5: Verificar e configurar a instalação

    Verifique a instalação:

Problemas gerais e boas práticas

Independentemente da plataforma, vale executar algumas verificações e configurações depois de instalar o Docker. Elas evitam muitos problemas posteriores.

Verificar se a instalação funcionou

Antes de começar, confirme que o Docker foi realmente instalado. Execute:

# Ver a versão do Docker
docker --version

# Ver a versão do Docker Compose, integrado às versões atuais do Docker
docker compose version

# Executar o contêiner de teste oficial Hello World
docker run hello-world

# Ver informações do sistema
docker info

docker run hello-world baixa e executa uma imagem pequena. Se aparecer “Hello from Docker!”, tudo está funcionando. docker info mostra detalhes como driver de armazenamento, driver de logs e quantidade de contêineres, sendo útil no diagnóstico.

Configurar um mirror de imagens, essencial para usuários na China

Na China, sem um mirror, o download de imagens pode ficar extremamente lento. O acesso ao repositório oficial Docker Hub é instável e costuma expirar.

Edite o arquivo de configuração do Docker — /etc/docker/daemon.json no Linux ou a guia Docker Engine das configurações do Docker Desktop no Windows e no Mac:

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://registry.docker-cn.com"
  ]
}

Salve e reinicie o Docker:

# Linux
sudo systemctl restart docker

# Mac/Windows: clique com o botão direito no ícone do Docker → Restart

Confirme se a configuração foi aplicada:

docker info | grep -A 5 "Registry Mirrors"

Os endereços configurados devem aparecer na saída.

Mirrors públicos na China também podem ficar instáveis, por isso vale configurar mais de uma alternativa. Alguns exigem uma conta, como o serviço de imagens de contêiner da Alibaba Cloud, mas costumam oferecer mais velocidade.

Limitar o tamanho dos logs para não ocupar todo o disco

Por padrão, os logs dos contêineres Docker não têm limite de tamanho. Um contêiner executado por muito tempo pode gerar dezenas de gigabytes e esgotar o disco. Isso já aconteceu comigo: quando o servidor ficou sem espaço, todos os contêineres pararam.

Adicione a configuração de logs ao daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Cada contêiner poderá manter até três arquivos de log de 10 MB. Ao ultrapassar o limite, os arquivos serão alternados e os mais antigos serão excluídos.

Se você precisa armazenar logs por muito tempo, use um sistema como ELK ou Loki em vez de mantê-los apenas no disco local.

Definir o driver de armazenamento

O desempenho varia bastante entre drivers de armazenamento. No Linux, overlay2 é recomendado e atualmente oferece o melhor desempenho. A maioria dos sistemas modernos já o usa por padrão, mas versões antigas podem usar devicemapper ou aufs, que são bem mais lentos.

Verifique o driver atual:

docker info | grep "Storage Driver"

Se não for overlay2, adicione ao daemon.json:

{
  "storage-driver": "overlay2"
}

Trocar o driver exige reiniciar o Docker e apaga todos os contêineres e imagens. Faça backup do que for importante.

Cinco cuidados para evitar problemas

Estas são as lições que tirei dos erros que encontrei:

  1. Consulte primeiro a documentação oficial. A documentação do Docker em docs.docker.com é clara. Muitos tutoriais encontrados em buscadores copiam outros textos e às vezes repetem erros. Começar pela documentação oficial economiza tempo.

  2. Confira a data do tutorial. O Docker muda rapidamente, e muitos tutoriais de 2020 a 2022 já estão desatualizados. Prefira materiais publicados nos últimos um ou dois anos.

  3. Use docker info e os logs. docker info mostra a configuração do sistema; docker logs <ID do contêiner> mostra a saída do contêiner; e journalctl -u docker.service, no Linux, mostra os logs do daemon. Em 90% dos casos, os logs oferecem uma pista.

  4. Não instale o Docker Desktop dentro de uma máquina virtual. O Docker Desktop já executa uma VM. Instalá-lo dentro de outra cria virtualização aninhada, com baixo desempenho e erros difíceis de explicar. Em uma máquina virtual, instale diretamente o Docker Engine.

  5. Não execute contêineres como root. Se um contêiner pode rodar com um usuário comum, não use root. É uma prática básica de segurança e especialmente importante em produção.

Lista rápida de diagnóstico

Se você não sabe por onde começar, verifique os itens nesta ordem. Isso costuma localizar cerca de 90% dos problemas comuns.

Etapa 1: ambiente básico

  • A versão do Docker é recente? Execute docker --version; prefira a versão estável mais recente
  • O sistema atende aos requisitos? Windows 10 19045+, Windows 11 22631+, macOS 13+ ou Ubuntu 20.04+
  • Há espaço em disco? Reserve pelo menos 10 GB e confira com df -h no Linux/Mac ou com o Explorador de Arquivos no Windows

Etapa 2: permissões e grupos no Linux/Mac

  • O usuário atual pertence ao grupo docker? Execute groups; a saída deve conter docker
  • Você entrou novamente na sessão depois de alterar o grupo? Este passo é fácil de esquecer; use newgrp docker ou faça logout e login
  • O socket tem as permissões corretas? ls -l /var/run/docker.sock deve mostrar srw-rw---- 1 root docker

Etapa 3: serviço e processos

  • O daemon do Docker está em execução?
    • Linux: sudo systemctl status docker
    • Mac: abra o Monitor de Atividade e procure Docker
    • Windows: procure Docker Desktop no Gerenciador de Tarefas
  • Há conflito de porta? Execute netstat -tulnp | grep docker no Linux ou lsof -i :2375 no Mac
  • O firewall está bloqueando? Desative-o temporariamente para testar com sudo systemctl stop firewalld ou sudo ufw disable

Etapa 4: arquivos de configuração

  • A sintaxe de daemon.json está correta? Valide o JSON ou faça backup, remova o arquivo e reinicie o Docker para testar
  • Há uma configuração hosts duplicada? Verifique daemon.json e o arquivo de serviço do systemd; não configure nos dois
  • O mirror está acessível? Execute ping registry.docker-cn.com ou curl https://docker.m.daocloud.io

Etapa 5: logs detalhados

Esta é a etapa mais importante; os logs normalmente contêm a mensagem exata do erro:

  • Linux: sudo journalctl -u docker.service -n 50
  • Mac: arquivos no diretório ~/Library/Containers/com.docker.docker/Data/log/
  • Windows: Visualizador de Eventos → Logs de Aplicativos e Serviços → Docker Desktop

Se você não entender o log, pesquise a mensagem completa no Google. Em geral, outra pessoa já encontrou o mesmo erro. Use a mensagem em inglês para obter resultados melhores.

Etapa 6: último recurso

Tente estas medidas, na ordem:

  1. Redefina o Docker Desktop para as configurações de fábrica em Docker Desktop → Troubleshoot → Reset to factory defaults
  2. Desinstale completamente e instale de novo, removendo também arquivos de configuração e cache
  3. Verifique se o antivírus bloqueou o programa; desative-o temporariamente para testar
  4. Tente outra versão; se a mais recente falhar, use uma versão estável um pouco anterior

Se nada funcionar, publique as informações do sistema, a versão do Docker e os logs completos no fórum oficial do Docker ou no Stack Overflow. Esses dados ajudam a comunidade a diagnosticar o problema.

Conclusão

Instalar o Docker pode ser simples ou trabalhoso. Cada plataforma tem suas armadilhas: no Windows, WSL 2 e virtualização; no Mac, a versão correspondente ao chip; no Linux, permissões e dependências. A boa notícia é que esses problemas seguem padrões conhecidos. Quando você identifica a causa, a correção costuma ser direta.

Os casos deste guia — permission denied, daemon que não inicia e dependências ausentes — cobrem cerca de 80% dos erros de instalação do Docker. Os outros 20% tendem a depender de ambientes específicos, mas saber ler logs, consultar a documentação e pesquisar a mensagem de erro em inglês ajuda a resolvê-los.

Antes de começar a usar o Docker, execute docker run hello-world para validar a instalação. Usuários na China devem configurar mirrors, ou o download de imagens pode ficar muito lento. Também vale limitar o tamanho dos logs para evitar surpresas com o disco cheio.

Quando surgir um problema, siga a lista de diagnóstico. Se ainda assim não conseguir resolver, procure o fórum oficial do Docker ou o Stack Overflow e inclua a mensagem de erro completa e a versão do sistema, em vez de perguntar apenas por que o Docker não instala.

Agora é hora de testar. Se este guia resolveu seu problema, compartilhe com alguém que também esteja enfrentando dificuldades para instalar o Docker. Menos tempo corrigindo a instalação significa mais tempo para desenvolver.

FAQ

O que fazer quando a instalação do Docker no Windows falha com WSL 2 installation is incomplete?
Siga três etapas:
1) Verifique a versão do Windows (pressione Win+R, digite winver; é necessário Windows 10 22H2 ou Windows 11 23H2)
2) Ative os recursos do WSL (Painel de Controle → Programas e Recursos → Ativar ou desativar recursos do Windows; marque 'Subsistema do Windows para Linux' e 'Plataforma de Máquina Virtual' e reinicie)
3) Atualize o WSL (PowerShell como administrador: wsl --update e wsl --set-default-version 2; é necessário WSL 2.1.5+)

Se ainda não funcionar, entre no BIOS e ative a virtualização (defina Virtualization Technology ou Intel VT-x/AMD-V como Enabled).
O que fazer quando o Docker Desktop no Mac fica em Starting... e não inicia?
Possíveis causas:

1) Versão errada para o chip:
• M1/M2 exige a versão Apple Silicon; Intel exige a versão Intel
• Para confirmar: menu Apple → Sobre Este Mac e verifique o tipo de chip
• Se instalou a versão errada, desinstale completamente e reinstale

2) Inicialização do daemon travada:
• Redefina o Docker Desktop: ícone do Docker na barra de menus → Troubleshoot → Reset to factory defaults
• Ou verifique conflito de porta: lsof -i :2375

3) Arquivo de configuração corrompido:
• Exclua ~/Library/Containers/com.docker.docker/Data/vms para forçar a reconstrução da VM

Em Macs M1/M2, instale o Rosetta 2 (softwareupdate --install-rosetta) se precisar executar imagens x86.
Como resolver permission denied ao executar docker ps no Linux?
Solução:
1) Adicione o usuário ao grupo docker: sudo usermod -aG docker $USER
2) Atualize os grupos: newgrp docker ou entre novamente na sessão (muita gente esquece esta etapa e continua vendo o erro)
3) Verifique: o comando groups deve mostrar docker e docker ps não deve mais falhar

Atenção: fazer parte do grupo docker equivale a ter privilégios de root, pois o Docker pode acessar todo o sistema de arquivos. Isso costuma ser aceitável em uma máquina pessoal de desenvolvimento, mas exige cautela em servidores de produção.

Se ainda não funcionar, confira a permissão do socket (ls -l /var/run/docker.sock deve mostrar srw-rw---- 1 root docker).
O que fazer quando faltam dependências ao instalar o Docker no Linux?
Causa principal: o repositório oficial do Docker não foi adicionado.

Etapas:
1) Remova versões antigas: sudo apt-get remove docker docker-engine docker.io containerd runc
2) Configure o repositório oficial do Docker:
• Instale ca-certificates curl gnupg lsb-release
• Adicione a chave GPG
• Configure o repositório
• No Linux Mint, use UBUNTU_CODENAME, não o número da versão do Mint
3) Atualize e instale: sudo apt-get update e sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
O que fazer quando o daemon do Docker não inicia?
Etapas de diagnóstico:
1) Verifique o estado do serviço:
• Linux: sudo systemctl status docker
• Mac: procure Docker no Monitor de Atividade
2) Inicie manualmente:
• Linux: sudo systemctl start docker e sudo systemctl enable docker
3) Consulte os logs detalhados:
• Linux: sudo journalctl -u docker.service -n 50
• Mac: diretório ~/Library/Containers/com.docker.docker/Data/log/

Causas comuns:
• Conflito com SELinux (CentOS/RHEL, desativação temporária: sudo setenforce Permissive)
• Erro de sintaxe na configuração (verifique /etc/docker/daemon.json)
• Bloqueio pelo firewall (desative-o temporariamente para testar)
Como verificar e configurar o Docker depois da instalação?
Verifique a instalação:
• Execute docker --version e docker compose version
• Execute docker run hello-world (se aparecer Hello from Docker!, está funcionando)
• Execute docker info

Configure um mirror de imagens (essencial para usuários na China):
• Edite /etc/docker/daemon.json e adicione registry-mirrors, como https://docker.m.daocloud.io
• Reinicie o Docker

Limite o tamanho dos logs:
• Adicione log-driver e log-opts ao daemon.json (max-size 10m e max-file 3, para evitar que os logs ocupem todo o disco)

Defina o driver de armazenamento:
• Verifique docker info; se não for overlay2, adicione storage-driver: overlay2 ao daemon.json
• Trocar o driver apaga todos os dados; faça backup antes
Qual é a lista rápida para diagnosticar problemas de instalação do Docker?
Verifique nesta ordem:

Primeiro, ambiente básico:
• Versão do Docker, versão do sistema e espaço em disco

Segundo, permissões e grupos (Linux/Mac):
• Comando groups, newgrp docker ou novo login e permissões do socket

Terceiro, serviço e processos:
• systemctl status docker, conflitos de porta e firewall

Quarto, arquivos de configuração:
• Sintaxe do daemon.json, configuração hosts duplicada e acesso ao mirror

Quinto, logs detalhados:
• journalctl -u docker.service ou diretório de logs

Sexto, último recurso:
• Redefinir o Docker Desktop, desinstalar completamente e reinstalar, desativar o antivírus ou trocar de versão

Essa lista localiza cerca de 90% dos problemas comuns.

19 min de leitura · Publicado em: 17 dez 2025 · Atualizado em: 4 set 2026

Comentários

Entre com GitHub para comentar

Easton BlogEaston Blog