npm install 에러 해결 10가지: EACCES, ENOSPC, Timeout, peer dependency

작성 0xmote · 2026년 5월 6일 · 20분 읽기 · 수정 2026년 9월 27일 초급 tutorial

이 글의 핵심

권한 에러가 난다고 sudo npm install부터 치면 나중에 더 꼬인 권한 문제를 만나게 됩니다. 각 에러의 증상과 원인을 먼저 구분하고, --legacy-peer-deps나 --force 같은 빠른 우회와 버전 조정 같은 근본 해결을 나눠 제시하며, 망가진 프로젝트를 복구하는 순서와 체크리스트까지 제공합니다.

들어가며

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  # 전역 설치

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 디렉토리에 대한 쓰기 권한이 없을 때 발생합니다. macOS와 대부분의 Linux 배포판은 시스템 안정성을 위해 /usr/local(그리고 그 하위의 lib/node_modules)을 관리자 권한이 있어야만 쓸 수 있도록 기본 설정해 두는데, npm은 -g 옵션으로 전역 패키지를 설치할 때 바로 이 디렉토리에 패키지를 풀어놓으려 시도합니다. 문제는 npm 자체가 시스템 패키지 관리자(apt, brew 등)와 같은 신뢰 수준을 갖고 있지 않다는 데 있습니다 — Node.js를 시스템 패키지 관리자로 설치했다면 npm의 전역 디렉토리도 시스템 소유가 되어, 매번 sudo를 붙여야만 전역 설치가 되는 구조적 불편이 생깁니다. 근본 해결책들이 모두 “npm의 전역 디렉토리를 사용자 소유 영역으로 옮긴다”는 한 가지 방향을 공유하는 이유가 여기 있습니다 — sudo로 매번 우회하는 대신, 애초에 권한 문제가 발생할 수 없는 위치에 npm을 두는 것입니다.

해결 방법 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

sudo로 우회하는 방식이 권장되지 않는 이유는 단순히 “권장 관례가 아니다”를 넘어섭니다 — sudo npm install은 해당 패키지의 설치 스크립트(많은 npm 패키지가 postinstall 훅으로 임의 코드를 실행합니다)를 관리자 권한으로 실행시키므로, 악의적이거나 손상된 패키지가 시스템 전체에 영향을 줄 수 있는 권한을 얻게 됩니다. 게다가 sudo로 설치된 파일들은 root 소유가 되어, 이후 sudo 없이 그 패키지를 업데이트하거나 삭제하려 하면 다시 권한 에러가 나는 악순환이 생기고, 프로젝트 로컬 node_modules에 root 소유 파일이 섞여 들어가면 이후 rm -rf node_modules조차 권한 문제로 실패하는 경우도 있습니다.

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 환경: 컨테이너 디스크 제한

세 원인 중 실무에서 가장 자주 놓치는 것이 inode 고갈입니다 — df -h로 확인하는 디스크 용량(바이트 단위)과 df -i로 확인하는 inode 개수(파일 시스템이 관리할 수 있는 파일·디렉토리 항목 수)는 완전히 별개의 자원이라, 디스크 여유 공간이 수십 GB 남아 있어도 inode를 모두 소진하면 ENOSPC가 그대로 발생합니다. node_modules가 이 문제의 전형적인 원인인 이유는, 각 패키지가 실제 크기와 무관하게 최소 하나 이상의 파일과 디렉토리 항목(각각 inode 하나씩 소비)을 만들어내기 때문입니다 — 중첩된 의존성 트리를 가진 대형 프로젝트라면 node_modules 하나가 수만~수십만 개의 inode를 소비할 수 있고, ext4 같은 파일 시스템은 포맷 시점에 inode 총량이 고정되어 나중에 늘릴 수 없으므로, 디스크 용량 확인만으로는 이 문제를 진단할 수 없습니다.

해결 방법

# 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  # 패키지 파일은 전역 저장소에 한 벌만 두고 하드링크로 연결

pnpm이 inode 문제를 근본적으로 완화하는 원리는 저장 방식 자체가 다르기 때문입니다 — npm은 프로젝트마다 각 패키지의 전체 사본을 node_modules에 개별적으로 복사하지만, pnpm은 전역 콘텐츠 주소 저장소(content-addressable store)에 패키지를 한 번만 저장해 두고, 프로젝트의 node_modules에는 그 저장소를 가리키는 하드링크/심볼릭 링크만 만듭니다. 같은 버전의 lodash를 열 개의 프로젝트가 쓰더라도 실제 파일은 디스크에 한 벌만 존재하므로, 디스크 용량뿐 아니라 inode 소비량도 프로젝트 수만큼 곱해지지 않고 크게 절약됩니다 절약되는 양은 여러 프로젝트가 같은 버전의 패키지를 얼마나 공유하느냐에 따라 달라집니다. 프로젝트가 하나뿐이라면 차이가 거의 없고, 비슷한 의존성을 쓰는 프로젝트가 많을수록 효과가 커집니다.

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 레지스트리 서버 문제

npm install이 네트워크에 특히 취약한 이유는 하나의 큰 요청이 아니라 의존성 트리 안의 패키지 개수만큼 개별 HTTP 요청을 레지스트리에 보내기 때문입니다 — React 앱 하나만 해도 수백 개의 간접 의존성을 가질 수 있고, 각각에 대해 메타데이터 조회와 tarball 다운로드가 개별적으로 이루어지므로 그중 단 하나만 타임아웃되어도 전체 설치가 실패로 끝날 수 있습니다. 회사 방화벽/프록시 환경에서 특히 자주 겪는 이유도 이와 관련이 있는데, 방화벽이 각 개별 요청을 심층 검사(deep packet inspection)하면서 지연이 누적되거나, 프록시가 레지스트리의 실제 IP를 화이트리스트에 반영하지 못해 일부 요청만 차단되는 경우가 흔합니다.

해결 방법 1: Timeout 증가

# 재시도 횟수와 재시도 간격을 늘림 (기본: fetch-retries 2, mintimeout 10초, maxtimeout 60초)
npm config set fetch-retries 5
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000
# fetch-timeout 기본값은 300000(5분)이므로, 이보다 작은 값으로 바꾸면 오히려 더 빨리 끊깁니다
npm config get fetch-timeout

해결 방법 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

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 버전과 현재 설치된 버전이 불일치합니다. peer dependency는 일반 의존성과 근본적으로 다른 계약입니다 — react-router-dom이 react를 일반 의존성으로 선언하면 자신만의 react 사본을 별도로 설치해 버려, 애플리케이션이 쓰는 react와 react-router-dom 내부의 react가 서로 다른 인스턴스가 되는 문제(리액트 훅이 두 개의 서로 다른 리액트 컨텍스트에서 충돌하는 등)가 생깁니다. peer dependency로 선언하면 “나는 이 버전대의 react가 호스트 프로젝트에 이미 설치되어 있다고 가정하고 그것을 공유해서 쓰겠다”는 뜻이 되어 이 문제를 피하지만, 그 대가로 호스트가 실제로 요구된 버전 범위를 만족시키지 못하면 npm이 이렇게 설치 자체를 거부합니다.

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

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

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

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

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

⚠️ 주의: --force는 런타임 에러를 유발할 수 있습니다. --legacy-peer-deps와 --force는 겉보기엔 비슷하지만 근본적으로 다른 우회입니다 — --legacy-peer-deps는 npm 7 이전처럼 peer dependency 검사 자체를 건너뛰고 일반 의존성처럼 다루는(각 패키지가 자기 버전을 따로 설치하도록 허용하는) 방식이고, --force는 검사는 하되 그 결과가 실패여도 강제로 설치를 진행합니다. 두 경우 모두 “버전이 호환되지 않을 수 있다”는 npm의 경고를 무시하는 것이므로, 설치는 성공해도 실제 런타임에 호환되지 않는 두 버전이 뒤섞여 예측 불가능한 동작(훅 오류, 타입 불일치 등)으로 이어질 수 있습니다 — 이것이 뒤이어 “근본 해결”로 버전 조정을 권장하는 이유입니다.

해결 방법 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

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+ 버전에서 의존성 트리 해결 알고리즘이 엄격해졌습니다. npm 6 이전에는 peer dependency 불일치가 그저 경고로만 표시되고 설치는 계속 진행되었지만, npm 7부터는 이를 실제 설치 실패로 취급하도록 바뀌었습니다 — 이는 npm이 자체적으로 더 정교한 의존성 해결 알고리즘(Yarn의 방식과 유사하게 더 정확한 트리를 구성하려는)을 도입한 결과이며, 이전 버전에서는 조용히 넘어가던 잠재적 버전 충돌이 npm 7 이상에서는 명시적인 에러로 드러나게 된 것입니다. 즉 이 에러가 npm 7로 업그레이드한 직후에 갑자기 나타나기 시작했다면, 그것은 npm이 더 엄격해진 것이지 프로젝트의 의존성 구성이 갑자기 나빠진 것은 아닙니다 — 원래도 존재하던 잠재적 문제가 이제야 표면화된 것입니다.

해결 방법 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 버전 강제 사용
    }
  }
}

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 방지: 유사 이름으로 설치 시도

이 중 “Private 패키지” 원인이 특히 헷갈리는 이유는, 에러 메시지가 “권한이 없다”가 아니라 “패키지가 존재하지 않는다(404)“로 나온다는 점입니다 — 이는 보안상 의도된 동작으로, 인증되지 않은 사용자에게 “이 패키지는 존재하지만 접근 권한이 없다”고 알려주면 그 패키지의 존재 자체(회사 내부 프로젝트명 등)가 노출되므로, npm 레지스트리는 인증 실패와 미존재를 구분하지 않고 똑같이 404로 응답합니다. 그래서 스코프 패키지(@mycompany/private-package)를 설치하다 404를 만나면, 오타를 의심하기 전에 .npmrc에 인증 토큰이 올바르게 설정되어 있는지부터 확인하는 것이 더 정확한 진단 순서입니다.

해결 방법

# 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

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 등이 해당됩니다. 이런 패키지들은 순수 JavaScript로는 성능이 부족하거나 시스템 라이브러리(libvips, OpenSSL 등)를 직접 호출해야 하는 기능을 제공하기 위해, npm install 시점에 node-gyp(Node.js용 네이티브 애드온 빌드 도구)를 통해 C/C++ 소스를 그 자리에서 컴파일합니다. 이 컴파일 과정은 순수 JS 패키지 설치와 전혀 다른 요구사항을 갖습니다 — 컴파일러(Xcode Command Line Tools, Visual Studio Build Tools, GCC 등), Python(node-gyp가 내부적으로 사용하는 빌드 시스템 gyp가 Python으로 작성됨), 그리고 플랫폼별 헤더 파일이 모두 갖춰져 있어야 하므로, 이 중 하나라도 빠지면 빌드가 실패합니다 — 이것이 “근본 해결”로 순수 JavaScript 대체 패키지(dart-sass 등)를 권장하는 이유이기도 합니다: 애초에 컴파일이 필요 없다면 이 모든 환경 의존성 문제 자체가 사라집니다.

해결 방법 - 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

npm Cache 손상

증상

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

원인

로컬 npm 캐시가 손상되어 패키지 무결성 검증에 실패합니다. npm은 한 번 다운로드한 패키지의 tarball을 ~/.npm/_cacache에 캐시해 두고, 이후 같은 패키지·버전을 다시 설치할 때 네트워크 요청 없이 그 캐시를 재사용합니다 — 이때 각 캐시 항목은 다운로드 당시 계산한 SHA-512 체크섬(sha512-xxxxx)과 함께 저장되고, 재사용 시점에 그 체크섬을 다시 계산해 비교함으로써 파일이 다운로드 이후 손상되지 않았는지 검증합니다. 이 무결성 검증에 실패한다는 것은 캐시된 파일 자체가 (디스크 오류, 강제 종료된 이전 설치, 디스크 공간 부족 상태에서의 쓰기 등으로) 부분적으로 손상되었다는 뜻이며, npm cache clean --force는 이런 손상 가능성이 있는 캐시를 통째로 지우고 다음 설치에서 레지스트리로부터 깨끗한 사본을 다시 받도록 강제합니다.

해결 방법

# 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

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을 직접 수정

package-lock.json이 이런 충돌에 특히 취약한 이유는 이 파일이 수백~수천 줄에 이르는, 사람이 직접 병합하도록 설계되지 않은 자동 생성 파일이기 때문입니다 — 두 브랜치가 서로 다른 패키지를 추가·업데이트했다면 Git의 텍스트 기반 병합 알고리즘은 그 의미(의존성 트리의 일관성)를 이해하지 못한 채 단순히 줄 단위로 병합을 시도하고, 그 결과 트리 구조상 앞뒤가 맞지 않는 lock 파일이 만들어지기 쉽습니다. npm 버전 차이도 근본적으로 같은 문제의 다른 얼굴입니다 — lock 파일 포맷 자체가 npm 버전(v1, v2, v3 lockfileVersion)에 따라 다르므로, 팀원 A가 npm 10으로 생성한 lock 파일을 npm 8을 쓰는 팀원 B가 열면 npm이 그 구조를 재해석하며 불필요한 변경사항을 만들어내고, 이것이 반복되면 매번 lock 파일에 의미 없는 diff가 쌓이는 원인이 됩니다 — 이것이 예방 조치로 .nvmrc와 engines 필드로 팀 전체의 Node.js/npm 버전을 통일하도록 권장하는 이유입니다.

해결 방법 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"
  }
}

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가 이를 초과합니다. 이 제한은 Windows API의 MAX_PATH 상수(드라이브 문자, 콜론, 백슬래시를 포함해 260자)에서 비롯된 수십 년 된 레거시 제약으로, NTFS 파일 시스템 자체는 훨씬 긴 경로를 지원하지만 대부분의 Win32 API 함수가 이 제한을 강제합니다. npm의 전통적인 flat하지 않은(중첩된) node_modules 구조 — 패키지 A가 패키지 B의 다른 버전을 요구하면 node_modules/A/node_modules/B처럼 계속 깊어지는 방식 — 는 macOS/Linux에서는 문제없지만, Windows에서는 C:\Users\사용자이름\Documents\프로젝트\node_modules\pkg1\node_modules\pkg2\node_modules\pkg3\...처럼 경로가 쌓여 260자를 손쉽게 넘어섭니다. 이것이 세 가지 해결책이 각기 다른 각도(운영체제 제한 자체를 완화, 애초에 경로를 짧게 유지, 중첩 구조를 아예 없애는 pnpm)에서 문제에 접근하는 이유입니다.

해결 방법 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

# 특징:
# - 전역 저장소 + 하드 링크로 프로젝트 간 중복 저장 제거
# - 이미 받은 패키지는 링크만 걸어 재설치가 빠름
# - 엄격한 의존성 관리

pnpm install

yarn

# 설치
npm install -g yarn

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

yarn install

Bun (최신)

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

# 특징:
# - 네이티브 구현 + 전역 캐시로 설치가 빠름
# - 내장 번들러/런타임
# - 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가지 해결법을 순서대로 시도하면 대부분의 문제는 원인을 좁힐 수 있습니다.

핵심 팁 3가지:

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

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

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

이 글의 핵심

들어가며

npm이란?

EACCES 권한 에러

증상

원인

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

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

피해야 할 방법

ENOSPC 디스크 용량 부족

증상

원인

해결 방법

inode 고갈 해결

ERR_SOCKET_TIMEOUT 네트워크 타임아웃

증상

원인

해결 방법 1: Timeout 증가

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

해결 방법 3: 프록시 설정

Peer Dependency 충돌

증상

원인

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

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

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

npm ERR! code ERESOLVE

증상

원인

해결 방법 1: 즉시 해결

해결 방법 2: 의존성 분석

package.json overrides 예제

Package Not Found (404)

증상

원인

해결 방법

Private npm 패키지 인증

node-gyp 빌드 실패

증상

원인

해결 방법 - macOS

해결 방법 - Windows

해결 방법 - Linux (Ubuntu)

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

npm Cache 손상

증상

원인

해결 방법

예방 조치

package-lock.json 충돌

증상

원인

해결 방법 1: 재생성

해결 방법 2: Git 충돌 해결

예방 조치

Windows 경로 길이 제한 (260자)

증상

원인

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

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

해결 방법 3: pnpm 사용

종합 체크리스트

디버깅 팁

상세 로그 확인

의존성 트리 분석

npm 설정 초기화

대안: 다른 패키지 매니저

pnpm (추천)

yarn

Bun (최신)

실전 예제: 프로젝트 복구

초보자를 위한 체크리스트

참고 자료

마무리

같이 보면 좋은 글