본문 바로가기
카테고리 없음

npm ERR! ERESOLVE unable to resolve dependency tree 오류, 의존성 충돌 해결법

바이브C 2026. 9. 28. 18:19

npm ERR! ERESOLVE unable to resolve dependency tree 오류, 의존성 충돌 해결법

npm으로 패키지를 설치하다가 npm ERR! ERESOLVE unable to resolve dependency tree라는 긴 오류가 나타나면 어디부터 확인해야 할지 막막합니다. 프로젝트는 정상적으로 실행되다가 새로운 라이브러리 하나를 설치한 뒤 갑자기 문제가 생기기도 하는데요.
 
npm ERESOLVE 오류는 대부분 npm이 여러 패키지가 요구하는 버전 조건을 동시에 만족시키지 못할 때 발생합니다.
 

무조건 node_modules를 삭제하거나 --force를 붙이기보다 어떤 패키지끼리 충돌하는지 먼저 확인하는 것이 중요합니다. 가장 쉬운 해결 순서부터 알아보겠습니다.

 
 

ERESOLVE unable to resolve dependency tree 뜻은?

Node.js 프로젝트에는 내가 직접 설치한 패키지만 있는 것이 아닙니다. 각 패키지가 다시 다른 라이브러리와 특정 버전을 요구하면서 하나의 dependency tree, 즉 의존성 트리를 구성합니다.
 
문제는 두 패키지가 서로 맞지 않는 버전을 요구할 때입니다. 예를 들어 어떤 플러그인이 특정 라이브러리의 이전 메이저 버전을 요구하는데 프로젝트에는 더 새로운 버전이 설치되어 있다면 npm이 충돌을 감지할 수 있습니다.

npm install some-package
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

 
따라서 이 메시지는 단순히 “npm 설치가 고장 났다”는 뜻보다 현재 패키지들의 버전 조건을 함께 만족시키기 어렵다는 의미로 이해하는 것이 좋습니다.
 
 

npm ERESOLVE에서 peerDependencies 확인하기

ERESOLVE 오류에서 특히 자주 확인하게 되는 것이 peerDependencies입니다. 라이브러리는 자신이 함께 동작할 것으로 기대하는 다른 패키지의 버전 범위를 peer dependency로 지정할 수 있습니다.

 
예를 들어 오류 메시지에 다음과 비슷한 내용이 표시될 수 있습니다.

Found: library@2.x
Could not resolve dependency:
peer library@"^1.x" from plugin@1.x

 

이 경우 핵심은 library와 plugin 사이의 버전 조건입니다. npm 자체를 다시 설치하기 전에 Found, Could not resolve dependency, peer 주변의 패키지 이름과 버전을 먼저 확인하세요.

 
 

package.json 버전부터 확인하는 것이 가장 쉬워요

충돌하는 패키지를 찾았다면 package.json에서 현재 프로젝트가 어떤 버전을 요구하고 있는지 확인합니다.

{
  "dependencies": {
    "some-library": "^2.0.0",
    "some-plugin": "^1.0.0"
  }
}

 
그다음 두 패키지 버전이 서로 호환되는 조합인지 확인하세요. 최근에 특정 라이브러리를 업그레이드한 직후 ERESOLVE가 시작됐다면 새 버전을 지원하는 플러그인 버전이 있는지 살펴보는 것도 중요합니다.
 
반대로 오래된 프로젝트를 설치하는 과정에서 오류가 발생했다면 현재 Node.js와 npm 환경에서 기존 의존성 조합이 그대로 재현되고 있는지도 함께 확인해 보세요.
 
 

패키지 버전을 맞춰 ERESOLVE 해결하기

가장 권장할 만한 해결 방향은 충돌하는 패키지들의 호환 가능한 버전을 찾는 것입니다. 단순히 오류 검사를 우회하는 것보다 실제 원인을 해결할 수 있기 때문입니다.

npm install some-package@호환버전

 
상황에 따라 핵심 라이브러리를 올리는 것이 맞을 수도 있고, 플러그인을 최신 호환 버전으로 변경하거나 기존 버전으로 맞추는 것이 필요할 수도 있습니다.
 
중요한 것은 무조건 최신 버전을 설치하는 것이 아닙니다. 현재 프로젝트의 다른 패키지와 함께 사용할 수 있는 버전인지를 기준으로 판단해야 합니다.
 
 

--legacy-peer-deps는 언제 사용할까?

ERESOLVE를 검색하면 자주 등장하는 명령이 --legacy-peer-deps입니다.

npm install --legacy-peer-deps

 
이 옵션은 peer dependency 충돌을 엄격하게 처리하는 현재 방식 대신 이전 npm에서 사용하던 방식에 가깝게 설치를 진행할 때 활용할 수 있습니다. 오래된 프로젝트를 일단 설치해 확인해야 하는 상황에서는 유용할 수 있습니다.
 
다만 명령이 성공했다고 패키지 호환성 문제가 사라졌다는 뜻은 아닙니다. 설치 이후 빌드나 실행 과정에서 다른 오류가 나타날 가능성이 있으므로 임시 우회책인지 실제 해결책인지 구분해야 합니다.
 
 

--force를 바로 사용하면 안 되는 이유

또 하나 자주 보이는 방법이 --force입니다.

npm install --force

 
이 옵션은 npm의 일부 보호 장치를 무시하고 설치를 진행하도록 강제할 수 있습니다. 설치 명령 자체는 넘어갈 수 있지만 서로 호환되지 않는 패키지 조합까지 프로젝트에 들어올 가능성이 있습니다.
 

따라서 ERESOLVE가 나타났다고 처음부터 --force를 붙이기보다 충돌하는 패키지와 버전을 먼저 파악하는 것이 좋습니다. 특히 실제 서비스 프로젝트라면 설치 성공 여부뿐 아니라 실행과 빌드의 안정성까지 확인해야 합니다.

 
 

--legacy-peer-deps와 --force 차이

버전 조정호환 가능한 의존성 구성가장 먼저 검토
--legacy-peer-depspeer dependency 처리 방식을 완화호환성 문제 확인 필요
--force충돌 경고를 무시하고 강제 진행 가능예상치 못한 실행 오류 주의

 

가능하다면 패키지 버전을 호환되는 조합으로 맞추는 것이 우선입니다. --legacy-peer-deps와 --force는 오류의 근본 원인을 이해한 뒤 필요성을 판단하는 편이 안전합니다.

 
 

node_modules 삭제와 재설치가 필요한 경우

package.json의 버전을 제대로 수정했는데 이전 설치 상태 때문에 문제가 이어진다면 의존성을 깨끗하게 다시 설치하는 방법을 검토할 수 있습니다. 하지만 ERESOLVE가 보인다고 무조건 node_modules부터 삭제할 필요는 없습니다.
 

특히 lock 파일에는 실제 설치할 패키지 버전 정보가 기록됩니다. 팀 프로젝트라면 package-lock.json을 임의로 삭제하기 전에 프로젝트의 의존성 관리 방식을 먼저 확인하세요.

 
버전 구성을 수정한 뒤에는 프로젝트 상황에 맞게 다시 설치하고, 오류 메시지가 어떻게 달라지는지 살펴보는 것이 좋습니다.
 
 

npm ls로 의존성 상태 확인하기

어떤 버전이 실제로 설치되어 있는지 확인하고 싶다면 npm ls를 활용할 수 있습니다.

npm ls

 
특정 패키지만 확인하고 싶다면 패키지 이름을 지정하는 방식도 유용합니다.

npm ls some-library

 
이를 통해 현재 프로젝트에서 해당 패키지가 어떤 버전으로 설치되어 있는지, 의존성 구조에서 어디에 사용되고 있는지 파악하는 데 도움을 받을 수 있습니다.
 
 

npm ERESOLVE가 계속 발생하는 주요 원인

1. 라이브러리와 플러그인의 요구 버전이 다른 경우
2. peerDependencies 조건을 만족하지 못한 경우
3. 핵심 프레임워크만 새로운 메이저 버전으로 올린 경우
4. 오래된 플러그인이 최신 라이브러리를 지원하지 않는 경우
5. package.json의 버전 조합이 서로 맞지 않는 경우
6. 기존 lock 파일과 변경된 의존성 구성이 충돌하는 경우
7. 다른 프로젝트의 package.json을 그대로 가져온 경우
 
결국 공통점은 패키지가 서로 기대하는 버전 조건이 맞지 않는 것입니다. 오류가 길더라도 처음부터 모든 문장을 해석할 필요는 없습니다. 먼저 충돌하는 패키지 두 개와 요구 버전을 찾아보세요.
 
 

ERESOLVE 가장 쉬운 해결 순서 체크리스트

1단계ERESOLVE 메시지에서 충돌 패키지 이름 확인
2단계Found와 peer dependency 요구 버전 비교
3단계package.json의 현재 버전 확인
4단계서로 호환되는 패키지 버전 확인
5단계필요한 패키지 버전을 업그레이드 또는 조정
6단계의존성을 다시 설치하고 빌드·실행 확인
7단계필요한 경우 --legacy-peer-deps 검토
8단계--force는 영향 범위를 이해한 뒤 신중하게 사용

 
 

npm ERESOLVE 오류를 예방하려면?

패키지를 업데이트할 때는 여러 핵심 라이브러리의 메이저 버전을 한꺼번에 변경하기보다 호환성을 확인하면서 단계적으로 진행하는 것이 좋습니다. 팀 프로젝트에서는 package.json뿐 아니라 lock 파일을 일관되게 관리하는 것도 중요합니다.
 
 

npm ERR! ERESOLVE unable to resolve dependency tree가 발생했다면 가장 먼저 해야 할 일은 npm을 재설치하는 것이 아니라 어떤 패키지 두 개의 버전 조건이 충돌하는지 찾는 것입니다. 오류 메시지의 Found, Could not resolve dependency, peer 부분을 확인해 보세요.

 

그다음 호환 가능한 버전으로 의존성을 맞추는 것이 핵심입니다. 충돌 확인 → package.json 확인 → 버전 조정 → 재설치 순서로 접근하고, --legacy-peer-deps와 --force는 차이를 이해한 뒤 사용하면 ERESOLVE 오류를 훨씬 안전하게 해결할 수 있습니다.

 
 
 
 
 

티스토리툴바