Error npm ERR! code EACCES al instalar paquetes en Node.js: Cómo solucionarlo paso a paso

¿Te has encontrado con este error al intentar instalar paquetes con npm?

npm ERR! code EACCES
npm ERR! syscall open
npm ERR! permission denied
npm ERR! Your cache folder contains root-owned files...

Este es uno de los errores más frustrantes y comunes que puedes encontrar al trabajar con Node.js, Express, Angular o cualquier entorno que utilice npm como gestor de paquetes, especialmente si estás en sistemas como Linux, macOS o incluso en WSL (Windows Subsystem for Linux).

La buena noticia es que la solución es sencilla, y en esta guía te explico paso a paso por qué ocurre este error y cómo solucionarlo correctamente para que puedas seguir trabajando sin interrupciones.

¿Qué significa el error EACCES?

El error EACCES es un tipo de error de permisos. Significa que npm intentó acceder a un archivo o directorio, pero no tiene los permisos necesarios para hacerlo.

En la mayoría de los casos, esto ocurre en la carpeta de caché de npm, que se encuentra en tu directorio personal:

~/.npm

Esta carpeta guarda información temporal, como paquetes descargados, metadatos, logs, etc., para que no tengas que volver a descargar todo en cada instalación. El problema surge cuando algunos de esos archivos han sido creados por el usuario root. Entonces, cuando intentas usar npm como un usuario normal, te encuentras con una barrera de permisos que impide que el sistema acceda a esos archivos.

¿Por qué ocurre este problema?

Generalmente, este error aparece después de haber usado el comando sudo al instalar paquetes de manera global, por ejemplo:

sudo npm install -g @angular/cli

Al ejecutar ese comando con sudo, estás permitiendo que npm se ejecute como superusuario, lo que provoca que todos los archivos que se creen durante ese proceso pasen a ser propiedad del usuario root.

A partir de ese momento, cualquier intento de usar npm sin sudo puede encontrar archivos que no te pertenecen, desencadenando el error EACCES.

Esto no solo afecta los paquetes instalados globalmente. En algunos casos, incluso paquetes locales pueden fallar si la caché de npm ya ha sido modificada por un proceso ejecutado como root.

Cómo verificar si el error se debe a permisos

Para comprobar si este es realmente el problema, puedes ejecutar el siguiente comando en tu terminal:

ls -la ~/.npm | grep root

Este comando te mostrará todos los archivos o carpetas dentro de .npm que pertenecen al usuario root. Si ves algo como esto:

drwxr-xr-x   5 root    staff   160 jun 26 13:44 _cacache
-rw-r--r--   1 root    staff   512 jun 26 13:44 .lock

¡Ya tienes el diagnóstico! Esos archivos propiedad de root son los que están causando el conflicto.

Solución: recuperar los permisos

La solución es cambiar la propiedad de todos los archivos de la carpeta ~/.npm para que vuelvan a ser tuyos (es decir, del usuario con el que estás trabajando actualmente).

Solo necesitas ejecutar este comando:

sudo chown -R $(whoami) ~/.npm

Lo que hace este comando es cambiar de forma recursiva (-R) la propiedad de todos los archivos y carpetas dentro de ~/.npm al usuario que está actualmente logueado (obtenido mediante $(whoami)).

Este paso debe hacerse con sudo, porque vas a modificar archivos que no te pertenecen.

Intenta instalar de nuevo

Una vez corregidos los permisos, puedes volver a intentar instalar tus paquetes:

npm install

Si todo salió bien, la instalación debería completarse sin errores.

Verificación final

Para asegurarte de que ya no hay archivos con permisos incorrectos, puedes volver a ejecutar:

ls -la ~/.npm | grep root

Si no aparece nada en la salida, ¡perfecto! Ya no quedan archivos propiedad de root en tu caché de npm.

También puedes ejecutar:

npm doctor

Este comando analiza tu entorno de desarrollo y te informa si detecta configuraciones problemáticas, versiones incompatibles o archivos corruptos.

Consejos adicionales para evitar este error en el futuro

Para que no vuelva a suceder este problema en tu instalación de Node.js, puedes aplicar los siguientes consejos:

• Evita usar sudo con npm a menos que sea absolutamente necesario. Si necesitas instalar paquetes globales, considera utilizar herramientas como nvm o fnm, que te permiten gestionar versiones de Node sin necesidad de permisos de administrador.
• Instala Node.js sin sudo: Si usas un gestor como nvm, puedes instalar Node en tu carpeta de usuario sin depender del sistema, evitando por completo este tipo de errores.
• Asegúrate de que tu entorno de desarrollo esté bien configurado, especialmente si trabajas en múltiples proyectos, con entornos virtuales, contenedores o máquinas remotas.

Conclusiones

El error EACCES de npm puede parecer intimidante al principio, pero una vez que entiendes su causa, es bastante fácil de solucionar. Lo importante es recordar que la gestión de permisos en sistemas Unix es muy estricta, y que el uso de sudo con herramientas como npm puede traer problemas.

Con una pequeña corrección de permisos, puedes volver a trabajar sin mayores interrupciones y con la tranquilidad de que tu entorno está limpio.

¿Te fue útil esta guía? ¡Compártela con tus colegas o déjame un comentario! Este tipo de errores son más comunes de lo que parece, y una solución clara puede ahorrarle mucho tiempo a más de uno.

Nota: La imagen de este artículo fue generada utilizando un modelo de inteligencia artificial.