npm install 했는데 ERESOLVE 의존성 충돌 에러 해결법

작성자:

ERESOLVE 의존성 충돌이 뜨면 당황스럽다. npm install을 실행했을 뿐인데 빨간 에러가 쏟아진다. 에러 메시지는 보통 이렇게 생겼다.

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from [email protected]
npm ERR! node_modules/some-ui-library
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps

ERESOLVE unable to resolve dependency tree 에러 메시지 맨 끝에 힌트가 있다. --force 또는 --legacy-peer-deps를 써보라고 한다. 해결법 4가지를 가장 빠른 것부터 정리했다.

ERESOLVE 의존성 충돌이 뜨는 이유

npm 7부터 peer dependency 충돌을 자동으로 무시하지 않는다. npm 6까지는 peer dependency가 맞지 않아도 경고만 내고 설치를 계속했다. npm 7부터는 아예 설치를 멈춘다.

peer dependency는 “나는 이 패키지를 직접 설치하지 않지만, 호스트 프로젝트에 특정 버전이 있어야 동작한다”는 선언이다. [email protected]이 react@^17.0.0을 peer dependency로 요구하는데 프로젝트에 react@18이 있으면 충돌이 발생한다. Node.js나 npm 버전을 올린 뒤 갑자기 에러가 뜨는 것도 이 때문이다.

npm 7 peer deps 정책 변경이 이 에러의 근본 원인이다. npm 6 이하를 쓰던 프로젝트를 npm 7 이상으로 업그레이드한 뒤 처음 npm install을 실행하면 이 에러를 처음 마주치는 경우가 많다.

npm 의존성 충돌을 엉킨 실타래로 표현한 일러스트

해결 방법 1: –legacy-peer-deps 플래그 (가장 빠름)

npm 6 방식으로 동작하게 한다. peer dependency 충돌을 경고만 하고 설치를 진행한다.

npm install --legacy-peer-deps

패키지 하나만 추가할 때도 동일하게 붙인다.

npm install some-library --legacy-peer-deps

같은 프로젝트에서 계속 이 옵션을 써야 한다면 .npmrc에 저장해둔다.

echo "legacy-peer-deps=true" > .npmrc

팀 프로젝트라면 .npmrc를 git에 커밋해서 팀원 모두가 같은 설정으로 설치하게 한다. CI/CD 파이프라인에도 자동으로 적용된다.

해결 방법 2: –force 플래그

--legacy-peer-deps로도 안 될 때 쓴다. 더 공격적으로 충돌을 무시하고 강제 설치한다.

npm install --force

--force는 충돌하는 패키지를 중복 설치하거나 덮어쓰는 방식으로 처리한다. 설치는 성공하지만 런타임에서 예상치 못한 에러가 날 수 있다. 먼저 --legacy-peer-deps를 시도하고, 그래도 안 될 때만 --force를 쓰자.

옵션동작안전성권장 상황
--legacy-peer-depsnpm 6 방식, peer dep 경고 후 설치상대적으로 안전대부분의 peer dep 충돌
--force충돌 강제 무시, 중복 설치 허용런타임 에러 가능성 높음legacy-peer-deps 실패 시

해결 방법 3: 충돌 패키지 버전 직접 맞추기 (근본 해결)

--legacy-peer-deps나 --force는 충돌을 무시하는 방법이다. 충돌 자체를 없애려면 버전을 맞춰야 한다.

먼저 어떤 패키지가 문제인지 찾는다.

# 설치된 react 버전 트리 확인
npm ls react

# 특정 라이브러리의 peer dependency 요구사항 확인
npm info some-library peerDependencies

최신 버전이 현재 환경과 호환된다면 업데이트한다.

npm install some-library@latest

버전 조정이 어렵다면 package.json의 overrides 필드를 쓴다. npm 8.3+에서 지원하는 방법으로, 특정 패키지의 의존성 버전을 프로젝트 수준에서 강제로 고정한다.

{
  "dependencies": {
    "some-ui-library": "^3.1.0"
  },
  "overrides": {
    "some-ui-library": {
      "react": "^18.0.0"
    }
  }
}

overrides를 추가한 뒤 npm install을 다시 실행하면 된다. .npmrc에 플래그를 넣는 것보다 명시적이고, 어떤 패키지의 어떤 의존성을 오버라이드했는지 코드에 기록이 남는다. 팀 프로젝트에서 가장 깔끔한 근본 해결책이다. (npm 공식 overrides 문서)

해결 방법 4: node_modules 초기화

오래된 node_modules나 package-lock.json이 버전 충돌의 원인인 경우다. 캐시된 의존성 트리가 실제 package.json 요구사항과 어긋나면 node_modules 초기화로 의존성 트리를 완전히 새로 계산하게 할 수 있다.

# macOS / Linux
rm -rf node_modules package-lock.json
npm install
# Windows PowerShell
Remove-Item -Recurse -Force node_modules, package-lock.json
npm install

초기화 후에도 같은 에러가 나면 환경 문제가 아니라 진짜 버전 충돌이다. 해결 방법 3으로 넘어간다.

npm 의존성 충돌 자주 묻는 질문

–legacy-peer-deps를 쓰면 위험한가?

대부분 안전하다. peer dependency 충돌이 항상 런타임 에러로 이어지지는 않는다. 라이브러리가 더 넓은 버전 범위를 실제로 지원하는데 package.json에 좁게 선언한 경우가 많다. 설치 후 관련 기능을 직접 테스트해서 확인하는 게 좋다.

yarn을 쓰면 이 에러가 안 나나?

yarn은 peer dependency 충돌을 경고로 처리하고 설치를 계속한다. 에러가 뜨지 않는다는 뜻이지, 충돌이 없다는 뜻이 아니다. pnpm은 npm 7과 비슷하게 엄격하게 처리한다.

팀 프로젝트에서 .npmrc 설정을 공유해도 되나?

권장한다. .npmrc를 git에 커밋하면 팀원 모두가 동일한 설치 환경을 유지할 수 있다. CI/CD 파이프라인에서도 자동 적용된다. 단, --force는 .npmrc에 넣지 말고 수동으로만 쓰자.

한줄 정리: ERESOLVE 의존성 충돌이 뜨면 --legacy-peer-deps 먼저 시도하고, 근본 해결이 필요하면 package.json overrides 필드로 버전을 명시적으로 고정하라.

댓글 남기기