Como corrigir o erro Docker permission denied no Ubuntu

O erro Docker permission denied (permissão negada) geralmente acontece quando sua conta de usuário não tem permissão para acessar o socket do Docker daemon ou determinados arquivos e diretórios necessários para a execução dos containers.

Essas restrições existem para evitar acessos não autorizados ao Docker. No entanto, no Ubuntu, elas podem atrapalhar bastante o fluxo de trabalho ao configurar ambientes de desenvolvimento.

Para corrigir o erro de permissão negada do Docker, siga estas seis soluções práticas:

1. Modifique o grupo do usuário. Adicione sua conta de usuário ao grupo docker para que você possa executar comandos do Docker sem o sudo.
2. Ajuste a propriedade de arquivos e diretórios. Atualize a propriedade dos arquivos de configuração e dos volumes montados para garantir que o mecanismo do Docker possa ler e gravar dados.
3. Verifique as permissões de socket. Confira os níveis de permissão do Docker Unix socket para garantir que o canal de comunicação com o daemon não esteja bloqueado.
4. Atualize permissões de execução de scripts. Certifique-se de que comandos no Dockerfile e scripts definidos em ENTRYPOINT tenham permissão de execução, evitando falhas ao iniciar containers.
5. Configure o acesso ao hardware. Permita que os containers acessem dispositivos específicos, como USBs ou GPUs, quando o erro estiver relacionado a permissões de hardware.
6. Reinicie o Docker daemon. Reinicie o serviço do Docker e sua sessão de usuário para aplicar corretamente todas as mudanças de permissão e grupo.

Pré-requisitos

Antes de corrigir o erro docker permission denied, verifique se o seu sistema Linux atende aos requisitos básicos para alterar configurações administrativas.

• Acesso administrativo. Você precisa de permissões sudo ou acesso como root para modificar grupos de usuários e permissões de arquivos.
• Verificação de grupo de usuários. Confirme a quais grupos sua conta pertence executando o comando groups $USER.

• Instalação do Docker. Confirme se o Docker está instalado e em execução executando o comando `docker –version`.

Embora as instruções deste guia sejam focadas no Ubuntu, elas também funcionam na maioria das distribuições baseadas em Debian.

1. Adicione seu usuário ao grupo Docker

A causa mais comum do erro de permissão negada é o usuário não fazer parte do grupo docker.

Por padrão, o daemon do Docker é executado como um serviço de propriedade do usuário root. Somente usuários do grupo docker podem se comunicar com ele sem usar sudo.

Para corrigir esse problema, adicione seu usuário atual ao grupo docker:

sudo usermod -aG docker $USER

Este comando atualiza sua conta de usuário adicionando-a ( -a ) ao grupo especificado ( -G ). Como resultado, seu usuário obtém permissão para acessar o socket do daemon do Docker e executar comandos do Docker diretamente.

Para que a mudança tenha efeito, faça logout e login novamente no sistema.

Depois de entrar novamente, confirme se o grupo foi aplicado corretamente executando:

id -nG

A saída deve incluir docker na lista de grupos.

Se quiser testar imediatamente sem sair da sessão, execute:

newgrp docker

Esse comando aplica a alteração de grupo apenas na sessão atual do terminal.

2. Corrija permissões de arquivos e diretórios

Se adicionar seu usuário ao grupo não resolver o problema, o problema pode estar em permissões incorretas em arquivos de configuração ou em volumes montados.

O Docker precisa de acesso de leitura e escrita aos arquivos de configuração — principalmente ao config.json.

Primeiro, verifique as permissões do diretório local de configuração do Docker:

ls -l ~/.docker/

Se a saída mostrar que os arquivos pertencem ao root em vez do seu usuário, altere a propriedade com o comando chown:

sudo chown -R "$USER":"$USER" "$HOME/.docker"

Esse comando altera de forma recursiva a propriedade do diretório .docker para o seu usuário atual.

Em seguida, verifique possíveis problemas com volumes montados. Quando você monta um diretório do host dentro de um container, o usuário dentro do container precisa ter permissão para ler e/ou gravar nesse diretório.

Por exemplo, ao iniciar um container com um volume:

docker run -v ~/data:/app/data ubuntu

Certifique-se de que o diretório do host ~/data tenha as permissões corretas. Você pode conceder acesso de leitura e gravação ao usuário ( u ) com o seguinte comando chmod:

chmod u+rw ~/data

Isso garante que o usuário que possui o diretório tenha permissões suficientes para gerenciar os dados dentro do volume montado.

3. Verifique as permissões do socket do Docker

O daemon do Docker se comunica por meio de um socket Unix localizado em /var/run/docker.sock. Se este socket tiver permissões incorretas, o cliente Docker não poderá enviar comandos para o daemon.

Para verificar as permissões atuais do socket, execute:

ls -l /var/run/docker.sock

O resultado esperado deve ser parecido com este:

srw-rw---- 1 root docker 0 Dec 18 10:00 /var/run/docker.sock

Essa saída indica que o socket pertence ao usuário root e ao grupo docker, com permissões de leitura e escrita para o grupo. Se você vir algo assim e seu usuário já fizer parte do grupo docker, a configuração do socket está correta.

Se o grupo não for “docker” ou as permissões forem diferentes, não as altere manualmente executando o comando “chmod 666 /var/run/docker.sock”.

Especialmente em ambientes de produção, isso representa um grave risco de segurança, pois concede acesso total ao Docker daemon para qualquer usuário do sistema — o que equivale, na prática, a acesso de nível root ao host.

Em vez disso, a abordagem correta é garantir que seu usuário pertença ao grupo docker. Quando o Docker daemon é iniciado, ele define automaticamente as permissões adequadas para o socket.

4. Corrija permissões no Dockerfile ou no script ENTRYPOINT

O erro docker permission denied também pode ocorrer dentro do container quando o script definido como ENTRYPOINT não tem permissão de execução.

Esse problema é comum quando scripts são copiados de sistemas que não usam permissões Unix, como o Windows, para o contexto de build do Docker. Nesse processo, o bit de execução pode ser perdido.

Quando isso acontece, o container falha ao iniciar porque não consegue executar o script definido nas instruções ENTRYPOINT ou CMD.

Para corrigir, adicione uma instrução RUN logo após o COPY no Dockerfile, garantindo permissão de execução para o script:

EXECUTE chmod +x /usr/local/bin/entrypoint.sh

Esse passo garante que o script continue executável independentemente das permissões no sistema host. Ele é especialmente importante ao criar imagens personalizadas que dependem de scripts de inicialização.

5. Conceda acesso a dispositivos para containers Docker

Se um container precisa interagir com dispositivos de hardware — como USB, webcam ou GPU — você pode encontrar um erro docker permission denied apontando para caminhos como /dev/ttyUSB0.

Por padrão, os contêineres são executados isoladamente e não podem acessar dispositivos do host. Para permitir o acesso, especifique explicitamente o dispositivo ao iniciar o contêiner usando a flag –device:

docker run --device=/dev/ttyUSB0 minha-imagem

Se o container precisar de permissões mais amplas, mas não de acesso total a dispositivos, você pode conceder capacidades específicas do Linux com a flag –cap-add:

docker run --cap-add=SYS_ADMIN minha-imagem

Essa abordagem segue o princípio do menor privilégio – isto é, conceder apenas as capacidades que o container realmente precisa. Algumas funcionalidades comuns incluem NET_ADMIN para configuração de rede e SYS_PTRACE para depuração.

Quando nem dispositivos específicos nem capacidades individuais resolvem, existe a opção –privileged:

docker run --privileged minha-imagem

Essa opção concede acesso total a todos os dispositivos do host e desativa grande parte dos mecanismos de isolamento do Docker.

Containers iniciados nesse modo podem obter controle de nível root sobre o host. Use –privileged apenas em ambientes locais e confiáveis ou quando não houver alternativas mais seguras.

Em ambientes de produção, prefira sempre –device para hardware específico ou –cap-add para permissões pontuais.

6. Reinicie o Docker e teste a configuração

Depois de aplicar mudanças em grupos de usuários ou corrigir permissões, é importante reiniciar o serviço do Docker para que o daemon reconheça a nova configuração.

Reinicie o Docker com systemctl:

sudo systemctl restart docker

Após a reinicialização, verifique se o erro foi resolvido executando o container padrão hello-world sem usar sudo:

docker run hello-world

Se a imagem for baixada, o container rodar corretamente e uma mensagem de boas-vindas aparecer no terminal, o problema de permissão foi corrigido com sucesso.

Caso o erro ainda persista, reinicie todo o sistema para garantir que todas as alterações de grupo e sessão sejam aplicadas:

sudo reboot

O que aprender a seguir em Docker?

Agora que sua instalação do Docker funciona sem erros de permissão, você já pode trabalhar com containers de forma segura e confiável.

Resolver problemas de ambiente, como o docker permission denied, é um passo essencial no aprendizado de Docker. Isso evita distrações com configurações e permite focar no que realmente importa: criar, executar e implantar aplicações.

Como próximo passo, vale aprofundar seu entendimento dos conceitos centrais do Docker. Nosso tutorial completo sobre Docker aborda temas fundamentais como gerenciamento de imagens, ciclo de vida dos containers, uso do Docker Compose, persistência de dados e redes entre containers — tudo o que você precisa para evoluir do básico para cenários mais avançados.

Todo o conteúdo dos tutoriais deste site segue os rigorosos padrões editoriais e valores da Hostinger.