Como Corrigir EACCES: Permission Denied no npm

Você executa npm install -g para instalar uma ferramenta de CLI e, em vez de uma instalação limpa, recebe isto:

npm ERR! code EACCES
npm ERR! errno -13
npm ERR! syscall access
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

Este erro EACCES do npm é um dos erros de permissão mais comuns do Node.js que os desenvolvedores enfrentam no macOS e no Linux. Veja por que ele acontece e como corrigi-lo da forma adequada.

Por Que Ocorrem Erros de Permissão Denied no npm

Quando você executa npm install -g, o npm escreve em um diretório de nível de sistema como /usr/local/lib/node_modules. Se você instalou o Node.js usando um instalador oficial ou um gerenciador de pacotes do sistema, esse diretório normalmente pertence ao root. Sua conta de usuário comum não tem acesso de escrita a ele, então a instalação falha.

Isso é um recurso de segurança dos sistemas baseados em Unix, não um bug. A correção não é sobrepor essas proteções — é dar ao npm um local que seu usuário já possua.

Distinção importante: Este artigo cobre erros de permissão em instalações globais. Se você está vendo erros de permissão dentro da pasta node_modules de um projeto local, a causa é diferente — geralmente uma incompatibilidade de propriedade de arquivos no diretório do seu projeto.

Corrigir Permissões de Instalação Global do npm: Duas Abordagens Seguras

Opção 1: Reinstalar o Node.js Usando um Gerenciador de Versões (Recomendado)

O npm recomenda oficialmente o uso de um gerenciador de versões do Node como o nvm para evitar completamente os erros EACCES. Quando o nvm instala o Node, ele coloca tudo dentro do seu diretório home — um local que seu usuário possui por padrão. Sem necessidade de acesso root, nunca.

Instale o nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/HEAD/install.sh | bash

Em seguida, instale o Node:

nvm install --lts

Depois disso, npm install -g funciona sem sudo ou alterações de permissão. Como bônus, o nvm permite alternar entre versões do Node por projeto — algo que nenhuma outra solução oferece.

Nota: Se você já tem um prefixo personalizado do npm configurado, o nvm gerencia seu próprio prefixo internamente. Não combine ambas as abordagens no mesmo ambiente, pois elas podem entrar em conflito.

Opção 2: Configurar um Diretório Global do npm de Propriedade do Usuário

Se você preferir não usar o nvm, pode redirecionar o local de instalação global do npm para um diretório que seu usuário possua. Esta é a alternativa descrita na documentação oficial do npm.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Em seguida, adicione o diretório bin ao seu PATH. Para bash, adicione isto ao ~/.profile ou ~/.bashrc:

export PATH=~/.npm-global/bin:$PATH

Para zsh, adicione a mesma linha ao ~/.zshrc e recarregue:

source ~/.zshrc

Verifique se funciona instalando um pacote sem sudo:

npm install -g npm-check-updates

E Sobre sudo npm install -g?

Evite. Executar sudo com o npm instala arquivos pertencentes ao root, o que cria mais problemas de permissão no futuro e introduz riscos reais de segurança — um pacote malicioso ou comprometido é executado com privilégios elevados. É uma solução de curto prazo que piora as coisas.

Uma Alternativa Rápida: Use npx

Se você só precisa de uma ferramenta de CLI ocasionalmente, talvez não precise de uma instalação global. O npx executa pacotes sem instalá-los globalmente, usando um pacote local ou buscando um temporariamente:

npm create vite@latest

Sem permissões necessárias, sem diretório global envolvido.

Qual Solução Você Deve Usar?

Conclusão

A causa raiz dos erros EACCES no npm install -g é quase sempre a mesma: o npm está tentando escrever em um diretório de propriedade do root. Corrija essa incompatibilidade na origem — seja usando o nvm ou apontando o npm para um diretório que você possua — e o erro desaparece para sempre.

Perguntas Frequentes

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.