npm install 시 EACCES 권한 에러가 계속 나옵니다

전역 패키지 디렉토리 권한 문제입니다. npm config로 사용자 디렉토리 설정 또는 nvm/fnm으로 Node.js 재설치를 추천합니다. sudo 사용은 권장하지 않습니다.

npm ERR! code ERESOLVE 해결 방법은?

--legacy-peer-deps 또는 --force 플래그를 사용하거나, package.json 의존성 버전을 조정하세요. 근본 해결은 패키지 버전 호환성 확인이 필요합니다.

npm install이 너무 느린데 어떻게 하나요?

npm cache clean --force 실행 후, registry를 빠른 미러(예: 카카오 미러)로 변경하거나 pnpm/yarn으로 전환을 고려하세요.

npm install 안될 때 해결법 10가지 - EACCES, ENOSPC, Timeout 완벽 정리

2026년 5월 6일 · 15분 읽기 · 수정 2026년 5월 6일 beginner tutorial

이 글의 핵심

`npm install` 실행 시 발생하는 EACCES, ENOSPC, Timeout, peer dependency 충돌 등 10가지 주요 에러의 원인과 즉시 적용 가능한 해결 방법을 실무 예제와 함께 정리한 완벽 가이드입니다.

들어가며

npm install 명령어는 Node.js 개발의 시작점입니다. 하지만 개발자라면 누구나 한 번쯤 “왜 안 되지?”라고 외친 경험이 있을 것입니다. 이 글은 실무에서 자주 발생하는 10가지 npm 에러와 검증된 해결 방법을 정리합니다.

초보자를 위한 한 줄: npm install은 package.json에 명시된 라이브러리를 다운로드하는 명령어지만, 권한/디스크/네트워크/버전 충돌 등 다양한 이유로 실패할 수 있습니다.

npm이란?

npm(Node Package Manager)은 JavaScript 패키지 관리자로, 전 세계 개발자가 공유하는 200만 개 이상의 오픈소스 라이브러리를 설치하고 관리합니다.

# 기본 사용법
npm install              # package.json 기반 전체 설치
npm install lodash       # 특정 패키지 설치
npm install -g typescript  # 전역 설치

1. EACCES 권한 에러

증상

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

원인

전역 패키지 설치 시 /usr/local 디렉토리에 대한 쓰기 권한이 없을 때 발생합니다.

해결 방법 1: npm 기본 디렉토리 변경 (권장)

# 1. 사용자 디렉토리에 npm 전역 패키지 저장소 생성
mkdir ~/.npm-global

# 2. npm 설정 변경
npm config set prefix '~/.npm-global'

# 3. 환경변수 추가 (~/.bashrc 또는 ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# 4. 설정 적용
source ~/.bashrc  # 또는 source ~/.zshrc

해결 방법 2: nvm 사용 (가장 권장)

# nvm 설치 (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Node.js 설치 (권한 문제 없음)
nvm install 20
nvm use 20

# 전역 설치 테스트
npm install -g typescript  # sudo 불필요

피해야 할 방법

# ❌ 절대 사용 금지! 보안 위험
sudo npm install -g some-package

2. ENOSPC 디스크 용량 부족

증상

npm ERR! code ENOSPC
npm ERR! syscall write
npm ERR! errno -28
npm ERR! nospc ENOSPC: no space left on device

원인

실제 디스크 부족: / 또는 /home 파티션 용량 초과
inode 고갈: 작은 파일(node_modules)이 많아 inode 소진
Docker 환경: 컨테이너 디스크 제한

해결 방법

# 1. 디스크 용량 확인
df -h

# 2. inode 사용량 확인
df -i

# 3. npm cache 삭제 (1~2GB 확보)
npm cache clean --force

# 4. 불필요한 node_modules 삭제
find . -name "node_modules" -type d -prune -exec rm -rf '{}' +

# 5. Docker인 경우 볼륨 크기 증가 (docker-compose.yml)
services:
  app:
    volumes:
      - ./:/app
    deploy:
      resources:
        limits:
          storage: 10G  # 증가

inode 고갈 해결

# 문제 확인
df -i
# /dev/sda1  100% (Iused 100%)

# 임시 해결: 오래된 프로젝트 정리
rm -rf ~/old-projects/*/node_modules

# 근본 해결: pnpm 사용 (심볼릭 링크로 inode 절약)
npm install -g pnpm
pnpm install  # node_modules 크기 70% 감소

3. ERR_SOCKET_TIMEOUT 네트워크 타임아웃

증상

npm ERR! code ERR_SOCKET_TIMEOUT
npm ERR! network request to https://registry.npmjs.org/lodash failed
npm ERR! network This is a problem related to network connectivity

원인

느린 인터넷 연결
회사 방화벽/프록시
npm 레지스트리 서버 문제

해결 방법 1: Timeout 증가

# timeout 기본값: 30초 → 60초로 증가
npm config set fetch-timeout 60000
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000

해결 방법 2: 빠른 미러 사용

# 카카오 npm 미러 (한국 사용자 추천)
npm config set registry https://registry.npmjs.org/
# 또는
npm config set registry https://registry.npmmirror.com/

# 설정 확인
npm config get registry

# 일회성 사용
npm install --registry=https://registry.npmmirror.com/

해결 방법 3: 프록시 설정

# 회사 프록시 설정
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 인증이 필요한 경우
npm config set proxy http://username:[email protected]:8080

# 프록시 해제
npm config delete proxy
npm config delete https-proxy

4. Peer Dependency 충돌

증상

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from [email protected]

원인

패키지가 요구하는 peer dependency 버전과 현재 설치된 버전이 불일치합니다.

해결 방법 1: —legacy-peer-deps (빠른 해결)

# peer dependency 검사 무시
npm install --legacy-peer-deps

# 프로젝트에 영구 적용
echo "legacy-peer-deps=true" >> .npmrc

해결 방법 2: —force (강제 설치)

# 경고 무시하고 강제 설치
npm install --force

⚠️ 주의: --force는 런타임 에러를 유발할 수 있습니다.

해결 방법 3: 버전 조정 (근본 해결)

// package.json
{
  "dependencies": {
    "react": "^18.2.0",
    "react-router-dom": "^6.8.0"  // React 18 호환 버전으로 업데이트
  }
}

# 업데이트 후 재설치
rm -rf node_modules package-lock.json
npm install

5. npm ERR! code ERESOLVE

증상

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: @testing-library/[email protected]
npm ERR! Found: [email protected]

원인

npm 7+ 버전에서 의존성 트리 해결 알고리즘이 엄격해졌습니다.

해결 방법 1: 즉시 해결

# 방법 A: legacy 모드
npm install --legacy-peer-deps

# 방법 B: overrides 사용 (package.json)
{
  "overrides": {
    "react": "18.2.0"  // 모든 하위 의존성에서 React 18 사용
  }
}

해결 방법 2: 의존성 분석

# 충돌하는 패키지 확인
npm ls react

# 출력 예시:
# ├─┬ [email protected]
# │ └── [email protected]  # 여기가 문제!
# └── [email protected]

# react-router-dom 업데이트
npm install react-router-dom@latest

package.json overrides 예제

{
  "name": "my-app",
  "dependencies": {
    "react": "^18.2.0",
    "some-old-library": "^1.0.0"
  },
  "overrides": {
    "some-old-library": {
      "react": "$react"  // 최상위 react 버전 강제 사용
    }
  }
}

6. Package Not Found (404)

증상

npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/some-package
npm ERR! 404 '[email protected]' is not in this registry

원인

오타: 패키지 이름이 잘못됨
삭제된 패키지: npm unpublish된 경우
Private 패키지: 인증이 필요한 경우
Typosquatting 방지: 유사 이름으로 설치 시도

해결 방법

# 1. npm 검색으로 정확한 이름 확인
npm search lodash

# 2. 웹에서 확인
# https://www.npmjs.com/package/lodash

# 3. Private 패키지 인증 (.npmrc)
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# 4. 스코프 패키지 레지스트리 설정
@mycompany:registry=https://npm.mycompany.com/

Private npm 패키지 인증

# 1. npm 로그인
npm login

# 2. 토큰 생성 (https://www.npmjs.com/)
# Account Settings > Access Tokens > Generate New Token

# 3. .npmrc 설정
echo "//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx" >> ~/.npmrc

# 4. 설치 테스트
npm install @mycompany/private-package

7. node-gyp 빌드 실패

증상

npm ERR! gyp ERR! build error
npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2
npm ERR! gyp ERR! not ok
npm ERR! node-gyp rebuild

원인

네이티브 모듈(C++ 애드온)을 컴파일할 수 없습니다. node-sass, bcrypt, sharp 등이 해당됩니다.

해결 방법 - macOS

# Xcode Command Line Tools 설치
xcode-select --install

# Python 설치 (node-gyp 요구사항)
brew install python3

# node-gyp 전역 설치
npm install -g node-gyp

해결 방법 - Windows

# 방법 1: 자동 설치 (관리자 권한 PowerShell)
npm install --global windows-build-tools

# 방법 2: 수동 설치
# 1. Visual Studio 2019 Build Tools 설치
#    https://visualstudio.microsoft.com/downloads/
# 2. Python 3.x 설치
#    https://www.python.org/downloads/

# Python 경로 설정
npm config set python "C:\Python39\python.exe"

해결 방법 - Linux (Ubuntu)

# 빌드 도구 설치
sudo apt-get update
sudo apt-get install -y build-essential python3

# node-gyp 설치
npm install -g node-gyp

근본 해결: 대체 패키지 사용

# ❌ node-sass (deprecated, 빌드 필요)
npm install node-sass

# ✅ dart-sass (순수 JavaScript, 빌드 불필요)
npm install sass

8. npm Cache 손상

증상

npm ERR! Unexpected end of JSON input while parsing near '...'
npm ERR! sha512-xxxxx
npm ERR! integrity checksum failed

원인

로컬 npm 캐시가 손상되어 패키지 무결성 검증에 실패합니다.

해결 방법

# 1. 캐시 완전 삭제
npm cache clean --force

# 2. 캐시 확인
npm cache verify

# 출력:
# Cache verified and compressed (~/.npm/_cacache)
# Content verified: 1234 (98765432 bytes)

# 3. 재설치
rm -rf node_modules package-lock.json
npm install

예방 조치

# 정기적 캐시 정리 (월 1회 추천)
npm cache clean --force

# 캐시 디렉토리 확인
npm config get cache
# /Users/username/.npm

# 캐시 비활성화 (CI 환경)
npm install --prefer-online

9. package-lock.json 충돌

증상

npm ERR! code ELOCKVERIFY
npm ERR! Verification failed while extracting package-lock.json
npm ERR! 
npm ERR! Different version of [email protected]

원인

Git Merge 충돌: 여러 브랜치의 package-lock.json 병합
npm 버전 차이: 팀원마다 다른 npm 버전 사용
수동 편집: package-lock.json을 직접 수정

해결 방법 1: 재생성

# package-lock.json 삭제 후 재생성
rm package-lock.json
npm install

# Git에 커밋
git add package-lock.json
git commit -m "chore: regenerate package-lock.json"

해결 방법 2: Git 충돌 해결

# 1. 충돌 확인
git status
# both modified:   package-lock.json

# 2. 한쪽 버전 선택 (예: main 브랜치)
git checkout --theirs package-lock.json

# 3. 재생성
npm install

# 4. 커밋
git add package-lock.json
git commit -m "chore: resolve package-lock conflict"

예방 조치

# 팀 npm 버전 통일 (.nvmrc 생성)
echo "20.11.0" > .nvmrc

# 팀원 사용법
nvm install  # .nvmrc 버전 자동 설치
nvm use      # .nvmrc 버전 사용

# package.json에 engines 명시
{
  "engines": {
    "node": ">=20.0.0",
    "npm": ">=10.0.0"
  }
}

10. Windows 경로 길이 제한 (260자)

증상

npm ERR! code EPERM
npm ERR! syscall open
npm ERR! path C:\Users\...\node_modules\...\...\very-long-path\file.js
npm ERR! errno -4048
npm ERR! Error: EPERM: operation not permitted

원인

Windows는 기본적으로 경로 길이를 260자로 제한합니다. 중첩된 node_modules가 이를 초과합니다.

해결 방법 1: 긴 경로 활성화 (Windows 10+)

# 관리자 권한 PowerShell 실행 후

# 레지스트리 수정
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# Git도 긴 경로 지원
git config --system core.longpaths true

# 재부팅 필요

해결 방법 2: 짧은 경로 사용

# 프로젝트를 C:\ 바로 아래로 이동
C:\Users\username\Documents\work\projects\my-app  # ❌ 길다
C:\work\my-app  # ✅ 짧다

해결 방법 3: pnpm 사용

# pnpm은 심볼릭 링크로 경로 단축
npm install -g pnpm
pnpm install

# node_modules 구조 비교:
# npm:  node_modules/lodash/node_modules/...  (깊이 5+)
# pnpm: node_modules/.pnpm/[email protected]/...  (깊이 고정)

종합 체크리스트

npm install 실패 시 순서대로 시도하세요:

캐시 정리

npm cache clean --force

의존성 재설치

rm -rf node_modules package-lock.json
npm install

권한 문제 확인

# 전역 설치 실패 시
npm config set prefix '~/.npm-global'

네트워크 문제 확인

npm config set registry https://registry.npmmirror.com/

의존성 충돌 해결

npm install --legacy-peer-deps

Node.js 버전 확인

node -v  # 프로젝트 요구사항과 일치하는지 확인
nvm install 20  # 필요 시 버전 변경

빌드 도구 설치 (네이티브 모듈 사용 시)

# macOS
xcode-select --install

# Windows (관리자 권한)
npm install --global windows-build-tools

# Linux
sudo apt-get install build-essential

디버깅 팁

상세 로그 확인

# 에러 전체 스택 출력
npm install --loglevel verbose

# 또는
npm install --dd

의존성 트리 분석

# 충돌하는 패키지 찾기
npm ls <package-name>

# 예: React 버전 충돌
npm ls react

# 출력:
# ├─┬ [email protected]
# │ └── [email protected] (충돌!)
# └── [email protected]

npm 설정 초기화

# 모든 npm 설정 확인
npm config list

# 설정 삭제
npm config delete proxy
npm config delete registry

# 공장 초기화
rm ~/.npmrc
npm config edit  # 기본값 생성

대안: 다른 패키지 매니저

npm이 계속 문제라면 대안을 고려하세요:

pnpm (추천)

# 설치
npm install -g pnpm

# 특징:
# - 디스크 사용량 70% 감소
# - 설치 속도 2배 빠름
# - 엄격한 의존성 관리

pnpm install

yarn

# 설치
npm install -g yarn

# 특징:
# - 안정적인 lock 파일
# - 워크스페이스 지원
# - Plug'n'Play 모드

yarn install

Bun (최신)

# 설치 (macOS/Linux)
curl -fsSL https://bun.sh/install | bash

# 특징:
# - 초고속 (npm 대비 10배 빠름)
# - 내장 번들러/런타임
# - npm 호환

bun install

실전 예제: 프로젝트 복구

팀 프로젝트를 clone했는데 npm install이 안 될 때:

# 1단계: 환경 확인
node -v      # Node.js 버전 확인
npm -v       # npm 버전 확인
cat .nvmrc   # 프로젝트 요구사항 확인

# 2단계: 올바른 Node.js 설치
nvm install
nvm use

# 3단계: 깨끗한 설치
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

# 4단계: 실패 시 legacy 모드
npm install --legacy-peer-deps

# 5단계: 여전히 실패 시 pnpm 시도
npm install -g pnpm
pnpm install

초보자를 위한 체크리스트

참고 자료

마무리

npm install 에러는 대부분 권한/디스크/네트워크/버전 충돌 중 하나입니다. 이 글의 10가지 해결법을 순서대로 시도하면 99%의 문제를 해결할 수 있습니다.

핵심 팁 3가지:

nvm 사용: 권한 문제 원천 차단
캐시 정리: 대부분의 간헐적 에러 해결
pnpm 고려: npm이 계속 불안정하다면 전환

에러 메시지를 구글에 검색할 때는 npm ERR! 뒤의 에러 코드(예: EACCES, ERESOLVE)를 함께 검색하면 정확한 해결책을 찾을 수 있습니다.

궁금한 점이 있다면 댓글로 남겨주세요! 🚀

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

들어가며

npm이란?

1. EACCES 권한 에러

증상

원인

해결 방법 1: npm 기본 디렉토리 변경 (권장)

해결 방법 2: nvm 사용 (가장 권장)

피해야 할 방법

2. ENOSPC 디스크 용량 부족

증상

원인

해결 방법

inode 고갈 해결

3. ERR_SOCKET_TIMEOUT 네트워크 타임아웃

증상

원인

해결 방법 1: Timeout 증가

해결 방법 2: 빠른 미러 사용

해결 방법 3: 프록시 설정

4. Peer Dependency 충돌

증상

원인

해결 방법 1: —legacy-peer-deps (빠른 해결)

해결 방법 2: —force (강제 설치)

해결 방법 3: 버전 조정 (근본 해결)

5. npm ERR! code ERESOLVE

증상

원인

해결 방법 1: 즉시 해결

해결 방법 2: 의존성 분석

package.json overrides 예제

6. Package Not Found (404)

증상

원인

해결 방법

Private npm 패키지 인증

7. node-gyp 빌드 실패

증상

원인

해결 방법 - macOS

해결 방법 - Windows

해결 방법 - Linux (Ubuntu)

근본 해결: 대체 패키지 사용

8. npm Cache 손상

증상

원인

해결 방법

예방 조치

9. package-lock.json 충돌

증상

원인

해결 방법 1: 재생성

해결 방법 2: Git 충돌 해결

예방 조치

10. Windows 경로 길이 제한 (260자)

증상

원인

해결 방법 1: 긴 경로 활성화 (Windows 10+)

해결 방법 2: 짧은 경로 사용

해결 방법 3: pnpm 사용

종합 체크리스트

디버깅 팁

상세 로그 확인

의존성 트리 분석

npm 설정 초기화

대안: 다른 패키지 매니저

pnpm (추천)

yarn

Bun (최신)

실전 예제: 프로젝트 복구

초보자를 위한 체크리스트

참고 자료

마무리

이 글이 도움이 되셨나요?