npm install 오류 해결 2026: EACCES, ERESOLVE, node-gyp 에러 원인과 해결

npm install 오류는 권한, 의존성 충돌, 네이티브 모듈 빌드 환경 문제로 나누어 확인하면 빠르게 좁힐 수 있습니다.

Node.js 프로젝트에서 npm install을 실행했는데 설치가 멈추면 먼저 오류 메시지의 종류를 나누어 보는 것이 좋습니다. 같은 설치 실패처럼 보여도 EACCES, ERESOLVE, node-gyp는 원인과 해결 순서가 다릅니다.

EACCES는 대체로 권한 문제, ERESOLVE는 의존성 충돌, node-gyp는 Python이나 C/C++ 빌드 도구 문제일 가능성이 큽니다. 아래 순서대로 확인하면 불필요하게 sudo, --force, 전체 재설치를 반복하지 않아도 됩니다.

npm install 오류 메시지 원문부터 확인하기

설치가 실패하면 터미널에서 가장 먼저 npm ERR!가 붙은 줄을 확인합니다. 긴 로그 전체를 읽기 어렵다면 아래 세 가지 메시지 중 어디에 가까운지 먼저 찾으면 됩니다.

EACCES 권한 오류

npm ERR! code EACCES
npm ERR! Error: EACCES: permission denied

EACCES는 현재 사용자에게 해당 폴더에 쓰기 권한이 없을 때 자주 발생합니다. 특히 Mac이나 Linux에서 전역 패키지를 설치할 때, 과거에 sudo npm install -g를 사용했을 때, Node.js를 여러 방식으로 설치했을 때 나타나기 쉽습니다.

ERESOLVE 의존성 충돌

npm ERR! ERESOLVE unable to resolve dependency tree

ERESOLVE는 프로젝트의 패키지 버전끼리 맞지 않을 때 발생합니다. 예를 들어 React, Vite, ESLint, TypeScript, Vue 같은 주요 패키지와 플러그인의 요구 버전이 서로 다르면 npm이 의존성 트리를 만들지 못하고 설치를 중단합니다.

node-gyp 빌드 오류

gyp ERR! configure error
gyp ERR! stack Error: not found: python

node-gyp 오류는 JavaScript만으로 설치되는 패키지가 아니라, 운영체제에서 직접 빌드해야 하는 네이티브 모듈이 포함되어 있을 때 발생합니다. Python, make, C/C++ 컴파일러, Visual Studio Build Tools, Xcode Command Line Tools 같은 빌드 환경이 없으면 설치가 실패할 수 있습니다.

EACCES, ERESOLVE, node-gyp 차이 한눈에 보기

npm install 오류는 메시지를 먼저 분류한 뒤 권한, 의존성, 빌드 환경 순서로 확인하면 원인을 빠르게 좁힐 수 있습니다.

오류	주요 원인	먼저 할 일
EACCES	npm 전역 설치 경로 권한 문제	Node 설치 경로와 npm prefix 확인
ERESOLVE	패키지 peer dependency 충돌	충돌 패키지 버전 확인
node-gyp	Python 또는 C/C++ 빌드 도구 누락	Python, 컴파일러, Node 버전 확인

npm install 오류가 발생하는 원인 3가지

1. npm 전역 설치 권한 문제

Mac이나 Linux에서 공식 설치 파일, Homebrew, nvm을 섞어 사용하면 npm 전역 설치 경로가 꼬일 수 있습니다. 전역 패키지가 시스템 폴더에 설치되도록 잡혀 있으면 일반 사용자 권한으로 쓰기 어렵고 EACCES 오류가 납니다.

먼저 현재 Node와 npm이 어디에서 실행되는지 확인합니다. Node 설치 방식 자체가 헷갈린다면 Node.js 설치 3가지 비교: nvm vs Homebrew vs 공식 설치를 함께 확인하면 원인을 좁히기 쉽습니다.

node -v
npm -v
npm config get prefix

# Mac / Linux
which node
which npm

# Windows
where node
where npm

2. package-lock.json 또는 node_modules 충돌

프로젝트를 오래 사용했거나 다른 사람의 저장소를 내려받은 경우, node_modules와 package-lock.json이 현재 Node 버전이나 npm 버전과 맞지 않을 수 있습니다. 이때는 캐시 확인 후 깨끗하게 다시 설치하면 해결되는 경우가 많습니다.

3. Node 버전 또는 node-gyp 빌드 환경 문제

일부 패키지는 설치 중에 네이티브 모듈을 빌드합니다. 이때 Node 버전이 프로젝트와 맞지 않거나 Python, 컴파일러, 빌드 도구가 없으면 node-gyp 오류가 발생합니다. 특히 오래된 프로젝트를 최신 Node에서 설치하거나, 최신 프로젝트를 오래된 Node에서 실행할 때 자주 나타납니다.

node -v
npm -v
python --version
python3 --version

빠른 해결 순서

무작정 모든 명령어를 실행하기보다 오류 종류에 따라 순서를 나누는 것이 안전합니다. 아래 명령어는 프로젝트 루트, 즉 package.json이 있는 폴더에서 실행하는 것을 기준으로 합니다.

1단계: npm 캐시 상태 확인

npm cache verify는 캐시를 무조건 삭제하는 명령이 아니라 현재 캐시 상태를 검증하는 명령입니다. 설치 오류가 반복될 때 가장 먼저 실행하기 좋습니다.

npm cache verify

2단계: node_modules 재설치

설치 폴더가 깨졌거나 이전 환경의 흔적이 남아 있다면 node_modules를 삭제한 뒤 다시 설치합니다. 잠금 파일을 유지하면 기존 의존성 버전을 최대한 보존할 수 있습니다.

# Mac / Linux
rm -rf node_modules
npm install

# Windows CMD
rmdir /s /q node_modules
npm install

# Windows PowerShell
Remove-Item -Recurse -Force node_modules
npm install

3단계: package-lock.json까지 정리 후 재설치

package-lock.json 자체가 현재 프로젝트 상태와 맞지 않는다고 판단될 때만 아래처럼 잠금 파일까지 삭제합니다. 팀 프로젝트에서는 삭제 후 변경된 package-lock.json을 바로 커밋하기보다 실행과 테스트 결과를 먼저 확인하는 것이 좋습니다.

# Mac / Linux
rm -rf node_modules package-lock.json
npm install

# Windows CMD
rmdir /s /q node_modules
del package-lock.json
npm install

# Windows PowerShell
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

4단계: 프로젝트 Node 버전 맞추기

프로젝트에 .nvmrc가 있다면 해당 버전을 사용하는 것이 우선입니다. .nvmrc가 없다면 README, 배포 환경, 팀 기준에 맞춰 Node LTS 버전을 선택합니다.

# .nvmrc가 있는 프로젝트
nvm install
nvm use

# LTS 버전을 새로 설치해 사용할 때
nvm install --lts
nvm use --lts

node -v
npm -v

5단계: ERESOLVE일 때 legacy-peer-deps 사용 기준

--legacy-peer-deps는 의존성 충돌을 근본적으로 고치는 명령이 아니라 peer dependency 검사를 느슨하게 해서 설치를 진행하는 우회 방법에 가깝습니다. 오래된 프로젝트를 임시로 실행해야 하거나, 충돌 원인을 확인하기 전에 로컬 실행만 급하게 해야 할 때 제한적으로 사용합니다.

npm install --legacy-peer-deps

새 프로젝트이거나 운영 배포가 필요한 프로젝트라면 먼저 충돌 패키지의 버전을 맞추는 것이 좋습니다. 예를 들어 React 버전과 관련 플러그인 버전, ESLint와 플러그인 버전, TypeScript와 빌드 도구 버전을 함께 확인합니다.

npm outdated
npm ls
npm explain <package-name>

EACCES 권한 오류 해결 방법

EACCES가 전역 설치에서 발생한다면 sudo npm install -g를 습관적으로 쓰는 방식은 피하는 편이 좋습니다. 당장은 설치될 수 있지만 나중에 일반 사용자 권한으로 설치한 패키지와 섞이면서 권한 문제가 반복될 수 있습니다.

nvm으로 Node를 다시 관리하기

Mac과 Linux에서는 Node 버전 매니저를 사용해 사용자 홈 디렉터리 안에서 Node와 npm을 관리하면 권한 문제가 줄어듭니다. 이미 여러 방식으로 Node를 설치했다면 현재 경로부터 확인합니다.

which node
which npm
npm config get prefix

nvm을 사용 중이라면 아래처럼 현재 프로젝트에 맞는 Node 버전을 선택합니다.

nvm list
nvm install --lts
nvm use --lts

npm install

npm 전역 설치 경로를 사용자 폴더로 바꾸기

전역 패키지를 꼭 npm으로 설치해야 한다면 npm prefix를 사용자 폴더 쪽으로 바꿀 수 있습니다. 아래 예시는 Mac과 Linux 기준입니다.

mkdir -p ~/.local
npm config set prefix ~/.local

# zsh 사용 예시
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

npm config get prefix

Windows에서는 같은 방식의 Unix 경로 설정을 그대로 적용하지 않습니다. Windows에서 권한 문제가 난다면 관리자 권한 PowerShell로 무조건 해결하기보다 Node 설치 방식, PATH 중복, nvm-windows 사용 여부를 먼저 확인하는 것이 좋습니다.

ERESOLVE 의존성 충돌 해결 방법

ERESOLVE unable to resolve dependency tree는 npm이 패키지들의 요구 버전을 동시에 만족시키지 못한다는 뜻입니다. 이때는 에러 로그에서 Found:, Could not resolve dependency:, peer가 붙은 줄을 중심으로 봅니다.

충돌 패키지 찾기

npm ls
npm explain <package-name>
npm outdated

npm explain은 특정 패키지가 왜 설치되는지 추적할 때 유용합니다. 예를 들어 react, eslint, typescript, vite처럼 핵심 패키지를 기준으로 어떤 패키지가 어떤 버전을 요구하는지 확인합니다.

해결 우선순위

순서	방법	기준
1	프로젝트 README 확인	권장 Node, npm, 패키지 버전이 있는지 확인
2	핵심 패키지 버전 맞추기	React, Vue, ESLint, TypeScript 계열 먼저 확인
3	--legacy-peer-deps 사용	오래된 프로젝트를 임시 실행할 때만 사용

# 특정 패키지 버전을 맞춰 설치하는 예시
npm install react@latest react-dom@latest

# 개발 의존성 업데이트 예시
npm install -D eslint@latest typescript@latest

패키지 버전을 올린 뒤에는 설치만 확인하지 말고 실행, 빌드, 테스트까지 확인합니다.

npm run dev
npm run build
npm test

node-gyp 오류 해결 방법

node-gyp는 Node.js 네이티브 애드온을 빌드하는 도구입니다. 따라서 일반 npm 패키지 설치보다 운영체제 의존성이 큽니다. 같은 프로젝트라도 Mac에서는 성공하고 Windows에서는 실패하거나, 반대로 Linux 서버에서만 실패할 수 있습니다.

Mac에서 확인할 것

Mac에서는 Xcode Command Line Tools가 없으면 C/C++ 컴파일러와 make를 찾지 못해 실패할 수 있습니다.

xcode-select --install

python3 --version
clang --version
make --version

Linux에서 확인할 것

Ubuntu 계열에서는 Python과 빌드 도구 패키지가 필요할 수 있습니다. 서버나 Dev Container에서는 최소 이미지에 빌드 도구가 빠져 있는 경우가 많습니다.

sudo apt update
sudo apt install -y python3 make g++ build-essential

python3 --version
g++ --version
make --version

Windows에서 확인할 것

Windows에서는 Python과 Visual Studio C++ Build Tools가 필요할 수 있습니다. Chocolatey를 사용한다면 아래처럼 설치할 수 있습니다.

choco install python visualstudio2022-workload-vctools -y

PowerShell에서 Python 경로를 확인한 뒤 다시 설치를 시도합니다.

py --list-paths
python --version
npm install

Python 경로를 명시해서 실행하기

Python이 설치되어 있는데도 not found: python이 나온다면 현재 터미널에서 Python 경로가 잡히지 않았을 수 있습니다. Mac과 Linux에서는 아래처럼 현재 Python 경로를 임시로 지정해 설치를 시도할 수 있습니다.

PYTHON="$(which python3)" npm install

Windows PowerShell에서는 실제 Python 설치 경로로 바꿔 실행합니다.

$Env:PYTHON="C:\Users\사용자명\AppData\Local\Programs\Python\Python312\python.exe"
npm install

Windows, Mac, Linux 차이

환경	자주 보는 문제	확인 명령어
Windows	PATH 중복, Python 경로, Visual Studio Build Tools 누락	where node, py --list-paths
Mac	nvm·Homebrew·공식 pkg 혼용, Xcode 도구 누락	which node, xcode-select --install
Linux	권한 문제, build-essential 누락, 서버 Node 버전 불일치	which npm, g++ --version

VSCode 터미널에서 확인할 것

외부 터미널에서는 설치가 되는데 VSCode 터미널에서만 실패한다면 VSCode가 사용하는 셸과 PATH가 다를 수 있습니다. 특히 zsh, bash, PowerShell, WSL, Dev Container를 오가면 같은 명령어라도 다른 Node를 바라볼 수 있습니다.

# 현재 셸 확인
echo $SHELL

# Mac / Linux
which node
which npm
echo $PATH

# Windows PowerShell
where.exe node
where.exe npm
$Env:Path

PATH를 수정한 뒤에는 VSCode 터미널만 새로 여는 것으로 부족할 수 있습니다. VSCode 창을 다시 불러오거나, 터미널 기본 프로필이 원하는 셸로 되어 있는지 확인합니다. VSCode 터미널 설정과 PATH가 자주 꼬인다면 VSCode 터미널 기본기: zsh 설정과 PATH 문제 해결을 함께 점검하면 좋습니다.

재발 방지 설정

한 번 설치가 성공해도 Node와 npm 환경이 정리되지 않으면 같은 오류가 반복될 수 있습니다. 아래 기준을 프로젝트마다 맞춰 두면 재발 가능성을 줄일 수 있습니다.

• Node 설치 방식은 nvm, Homebrew, 공식 설치 중 하나로 정리합니다.
• 팀 프로젝트에는 .nvmrc로 Node 버전을 남겨 둡니다.
• package-lock.json은 특별한 이유가 없으면 저장소에 함께 관리합니다.
• 전역 설치보다 프로젝트 로컬 설치와 npx, npm exec 사용을 우선합니다.
• sudo npm install -g는 권한 문제가 반복될 수 있으므로 습관적으로 사용하지 않습니다.

# 현재 Node 버전을 .nvmrc에 기록
node -v > .nvmrc

# 다음부터 프로젝트에서 사용
nvm install
nvm use

Homebrew, pyenv, nvm을 함께 쓰는 Mac 환경에서는 PATH 순서가 설치 오류의 원인이 되기도 합니다. 여러 도구가 같은 명령어를 가리키는 상황이라면 Homebrew·pyenv·nvm PATH 꼬였을 때 zshrc 수정 순서를 기준으로 정리하는 것이 좋습니다.

자주 쓰는 npm install 오류 해결 명령어

목적	명령어	설명
버전 확인	node -v && npm -v	현재 Node와 npm 버전 확인
캐시 확인	npm cache verify	npm 캐시 상태 검증
깨끗한 설치	rm -rf node_modules && npm install	설치 폴더 재생성
버전 맞추기	nvm install && nvm use	.nvmrc 기준으로 Node 사용
의존성 우회	npm install --legacy-peer-deps	오래된 프로젝트 임시 설치

공식 자료로 더 확인하기

npm 권한 오류, peer dependency 처리 방식, node-gyp 빌드 요구 사항은 npm과 Node.js 버전에 따라 달라질 수 있습니다. 설치 오류가 반복되거나 팀 프로젝트에 적용해야 한다면 아래 공식 문서를 기준으로 현재 환경에 맞는 설정을 다시 확인하는 것이 좋습니다.

함께 보면 좋은 글

자주 묻는 질문

npm install 오류는 메시지를 먼저 분류한 뒤 권한, 의존성, 빌드 도구 순서로 좁혀가면 대부분 빠르게 정리할 수 있습니다.