npm: EACCES permission denied при установке глобальных пакетов

#Что означает ошибка

«npm ERR! code EACCES … permission denied» означает, что у вашего пользователя нет прав записи в каталог, куда npm устанавливает пакеты, чаще всего в системный /usr/lib/node_modules или /usr/local/lib/node_modules. Решение с sudo npm install -g работает, но создаёт проблемы с правами в дальнейшем и небезопасно: скрипты пакетов выполняются от root. Правильнее настроить пользовательский каталог для глобальных пакетов или использовать менеджер версий Node (nvm).

#Причины и решения

#Пошаговое решение

1. Определите prefixОшибка EACCES при npm install -g на Linux/macOS означает отсутствие прав записи в выбранный каталог; инструкция с пользовательским каталогом ниже НЕ предназначена для Windows. Откройте «Терминал» и выполните npm config get prefix; запишите вывод. Если там системный путь вроде /usr/local, не меняйте его владельца рекурсивно и не устанавливайте npm-пакеты глобально через sudo. Самый простой вариант — установить Node.js через диспетчер версий, а настройка собственного каталога ниже служит альтернативой.
2. Создайте каталогЕсли вы выбрали вариант с пользовательским каталогом, в терминале Linux/macOS выполните mkdir -p "$HOME/.local". Команда создаст каталог внутри вашего профиля; обычно права администратора не нужны. Убедитесь, что он существует командой ls -ld "$HOME/.local"; если видите «Permission denied» даже дома, проверьте собственность каталога прежде чем продолжать.
3. Задайте prefixВ том же терминале выполните npm config set prefix "$HOME/.local", затем npm config get prefix. Во втором выводе должен появиться абсолютный путь к вашему домашнему каталогу. Важно: ставьте двойные кавычки, не записывайте ~ в одинарных кавычках — тогда символ может остаться буквальным и путь окажется неправильным.
4. Добавьте в PATHНа Linux с bash откройте ~/.profile в текстовом редакторе (nano ~/.profile), в конец один раз добавьте export PATH="$HOME/.local/bin:$PATH", сохраните Ctrl+O → Enter → Ctrl+X. Для zsh добавьте в ~/.zprofile строку source ~/.profile, если она ещё не существует. Для другой командной оболочки используйте её файл запуска. Каталог .local/bin должен быть в PATH именно в новой терминальной сессии.
5. ПрименитеВ терминале bash выполните source ~/.profile или полностью закройте и заново откройте окно; для zsh предварительно настройте ~/.zprofile, затем откройте новое окно. Проверьте echo "$PATH": в списке должен быть путь /home/ваш_пользователь/.local/bin (на macOS каталог другой). Если его нет, убедитесь, что редактировали файл запуска вашей оболочки.
6. Исправьте кэшШаг нужен лишь когда в сообщении EACCES упомянут кэш ~/.npm, а не каталог установки. Выполните ls -ld "$HOME/.npm", чтобы узнать владельца. Если каталог действительно принадлежит root после старых запусков sudo, администратор может исправить собственность только этого каталога: sudo chown -R "$(id -u):$(id -g)" "$HOME/.npm". Эта команда меняет владельца файлов: не применяйте её к системному node_modules или чужим каталогам.
7. Повторите установкуПосле настройки выполните пример из документации npm install -g npm-check-updates без sudo; после окончания введите ncu --version. Если оболочка сообщает command not found, вернитесь к шагу с PATH. Для нужного пакета замените npm-check-updates на точное имя из официальной инструкции проекта; используйте npx вместо постоянной установки, если команда нужна однократно.
8. Используйте nvmАльтернативный, рекомендуемый npm вариант — диспетчер версий Node.js. Откройте документацию Node.js/npm по установке через менеджер версий для вашей ОС; установите менеджер по официальной инструкции, затем версию Node LTS и проверьте node -v, npm -v, npm config get prefix. Не смешивайте одновременно два способа: если переходите на менеджер версий, удалите ранее внесённый пользовательский prefix командой npm config delete prefix в нужной конфигурации и откройте новый терминал.
9. Дополнительная команда по теме

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   Альтернатива менеджеру версий Node; без автоматической рекурсивной смены владельца и без обновления npm@latest

   # Linux/macOS, пользовательский каталог; НЕ запускать с sudo

   mkdir -p "$HOME/.local"

   npm config set prefix "$HOME/.local"

   # В ~/.profile один раз добавьте: export PATH="$HOME/.local/bin:$PATH"

   # Для zsh подключите ~/.profile из ~/.zprofile и откройте новый терминал

   npm config get prefix

   # Проверка после настройки PATH

   npm install -g npm-check-updates

   ncu --version

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

Если ошибка возникает при npm install в рабочем проекте, а не при глобальной установке, откройте терминал в каталоге проекта и посмотрите владельца именно проблемных файлов (ls -ld . node_modules и полный путь из сообщения EACCES). Если файлы принадлежат другому пользователю или созданы контейнером, согласуйте с владельцем исправление прав конкретного каталога; не запускайте рекурсивный chown над всем проектом автоматически. В Docker настройте пользователя контейнера и владельца подключённого тома. Для установки из сохранённого package-lock.json в контролируемом проекте используйте npm ci, понимая, что эта команда пересоздаёт node_modules.

Если ошибка возникает в CI или контейнере, проверьте пользователя, которому принадлежит каталог кэша npm и рабочая папка, а также права подключённых томов. Когда проблема связана только с пересоздаваемыми зависимостями проекта, сначала сохраните важные локальные изменения и убедитесь в наличии правильного package-lock.json, затем запустите npm ci из каталога нужного проекта: эта команда сама удаляет и переустанавливает содержимое node_modules. Для глобального EACCES предпочтительнее менеджер версий Node.js или пользовательский prefix из инструкции выше.