Cómo solucionar EACCES: Permission Denied en npm

Ejecutas npm install -g para instalar una herramienta de CLI y, en lugar de una instalación limpia, obtienes esto:

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 error EACCES de npm es uno de los errores de permisos de Node.js más comunes con los que se topan los desarrolladores en macOS y Linux. Aquí explicamos por qué ocurre y cómo solucionarlo correctamente.

Por qué ocurren los errores de permisos en npm

Cuando ejecutas npm install -g, npm escribe en un directorio del sistema como /usr/local/lib/node_modules. Si instalaste Node.js mediante un instalador oficial o un gestor de paquetes del sistema, ese directorio normalmente pertenece a root. Tu cuenta de usuario regular no tiene acceso de escritura, así que la instalación falla.

Esto es una característica de seguridad de los sistemas basados en Unix, no un error. La solución no consiste en saltarse esas protecciones, sino en darle a npm una ubicación que tu usuario ya posea.

Distinción importante: Este artículo cubre los errores de permisos en instalaciones globales. Si estás viendo errores de permisos dentro de la carpeta node_modules de un proyecto local, la causa es distinta: normalmente una discrepancia en la propiedad de los archivos en el directorio de tu proyecto.

Soluciones para los permisos de instalación global de npm: dos enfoques seguros

Opción 1: Reinstalar Node.js usando un gestor de versiones (recomendado)

npm recomienda oficialmente usar un gestor de versiones de Node como nvm para evitar por completo los errores EACCES. Cuando nvm instala Node, coloca todo dentro de tu directorio home, una ubicación que tu usuario posee por defecto. Nunca se requiere acceso root.

Instala nvm:

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

Luego instala Node:

nvm install --lts

Después de eso, npm install -g funciona sin sudo ni cambios de permisos. Como ventaja adicional, nvm te permite cambiar entre versiones de Node por proyecto, algo que ninguna otra solución ofrece.

Nota: Si ya tienes configurado un prefix personalizado para npm, nvm gestiona su propio prefix internamente. No combines ambos enfoques en el mismo entorno, ya que pueden entrar en conflicto.

Opción 2: Configurar un directorio global de npm propiedad del usuario

Si prefieres no usar nvm, puedes redirigir la ubicación de instalación global de npm a un directorio que pertenezca a tu usuario. Esta es la alternativa que se describe en la documentación oficial de npm.

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

Luego añade el directorio bin a tu PATH. Para bash, agrega esto a ~/.profile o ~/.bashrc:

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

Para zsh, añade la misma línea a ~/.zshrc y luego recarga:

source ~/.zshrc

Verifica que funciona instalando un paquete sin sudo:

npm install -g npm-check-updates

¿Y qué pasa con sudo npm install -g?

Evítalo. Ejecutar sudo con npm instala archivos propiedad de root, lo que genera más problemas de permisos a futuro e introduce riesgos de seguridad reales: un paquete malicioso o comprometido se ejecutaría con privilegios elevados. Es una solución a corto plazo que empeora las cosas.

Una alternativa rápida: usar npx en su lugar

Si solo necesitas una herramienta de CLI ocasionalmente, puede que no requieras una instalación global. npx ejecuta paquetes sin instalarlos globalmente, usando un paquete local o descargando uno temporalmente:

npm create vite@latest

Sin permisos requeridos, sin directorio global involucrado.

¿Qué solución deberías usar?

Conclusión

La causa raíz de los errores EACCES en npm install -g es casi siempre la misma: npm está intentando escribir en un directorio propiedad de root. Corrige esa discrepancia en el origen, ya sea usando nvm o apuntando npm a un directorio que poseas, y el error desaparecerá para siempre.

Preguntas frecuentes

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.