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

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
Step 1: Instalação no Windows
Verifique a versão do Windows: -
2
Step 2: Instalação no Mac
Confirme o tipo de chip do Mac: -
3
Step 3: Instalação no Linux
Remova versões antigas: -
4
Step 4: Resolver Permission Denied no Linux
Adicione o usuário ao grupo docker: -
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:
-
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.
-
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.
-
Use
docker infoe os logs.docker infomostra a configuração do sistema;docker logs <ID do contêiner>mostra a saída do contêiner; ejournalctl -u docker.service, no Linux, mostra os logs do daemon. Em 90% dos casos, os logs oferecem uma pista. -
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.
-
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 -hno 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 dockerou faça logout e login - O socket tem as permissões corretas?
ls -l /var/run/docker.sockdeve mostrarsrw-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
- Linux:
- Há conflito de porta? Execute
netstat -tulnp | grep dockerno Linux oulsof -i :2375no Mac - O firewall está bloqueando? Desative-o temporariamente para testar com
sudo systemctl stop firewalldousudo ufw disable
Etapa 4: arquivos de configuração
- A sintaxe de
daemon.jsonestá correta? Valide o JSON ou faça backup, remova o arquivo e reinicie o Docker para testar - Há uma configuração
hostsduplicada? Verifiquedaemon.jsone o arquivo de serviço do systemd; não configure nos dois - O mirror está acessível? Execute
ping registry.docker-cn.comoucurl 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:
- Redefina o Docker Desktop para as configurações de fábrica em Docker Desktop → Troubleshoot → Reset to factory defaults
- Desinstale completamente e instale de novo, removendo também arquivos de configuração e cache
- Verifique se o antivírus bloqueou o programa; desative-o temporariamente para testar
- 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?
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?
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?
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?
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?
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?
• 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?
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
Guia prático Docker
Se você chegou pela busca, o caminho mais rápido é ir para o post anterior ou próximo desta série.
Anterior
Docker vs. máquina virtual: entenda as diferenças de desempenho e saiba quando usar cada um
Está em dúvida entre Docker e máquina virtual? Este guia explica as diferenças essenciais, compara o desempenho com dados práticos e traz uma árvore de decisão para ajudar você a escolher em 5 minutos.
Parte 1 de 34
Próximo
Dockerfile para iniciantes: crie sua primeira imagem Docker do zero
Aprenda a escrever um Dockerfile passo a passo, entenda instruções essenciais como FROM, RUN e COPY, evite erros comuns e acompanhe um exemplo prático com Node.js.
Parte 3 de 34



Comentários
Entre com GitHub para comentar