npm ERESOLVE unable to resolve dependency tree 해결: --legacy-peer-deps 쓰기 전에
npm install 중 npm error code ERESOLVE / unable to resolve dependency tree가 나오면, 설치하려는 패키지가 요구하는 버전(peer dependency)과 이미 설치된 버전이 맞지 않는다는 뜻입니다. 가장 안전한 해결은 버전을 서로 맞추는 것이고, --legacy-peer-deps와 --force는 오류만 숨기는 임시방편입니다.
아래 내용은 2026년 11월 20일 리눅스에서 Node.js 22.23과 npm 10.9.9로 react@18과 react-dom@17을 일부러 섞어 설치하며 직접 확인한 결과입니다.
1. 오류 원문 읽는 법
react 18.3.1이 설치된 프로젝트에 npm i react-dom@17.0.2를 실행했을 때 나온 메시지입니다.
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error Found: react@18.3.1
npm error node_modules/react
npm error react@"^18.3.1" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"17.0.2" from react-dom@17.0.2
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
- Found: 지금 프로젝트에 있는 버전 → react 18.3.1
- Could not resolve dependency / peer: 새 패키지가 요구하는 버전 → react-dom 17.0.2는 react 정확히 17.0.2를 원함
즉 "react는 18인데 react-dom은 17용"이라 같이 못 쓴다는 말입니다. npm 7부터는 peer dependency를 자동으로 검사해서 이런 경우 설치를 멈춥니다.
2. 해결 1: 요구 버전을 확인하고 맞추기 (추천)
먼저 그 패키지가 무엇을 요구하는지 봅니다.
npm view react-dom@18.3.1 peerDependencies
결과는 { react: '^18.3.1' }였습니다. 그래서 react-dom도 18.3.1로 맞춰 설치하니 오류 없이 끝났습니다.
npm i react-dom@18.3.1
added 2 packages
npm ls react react-dom
+-- react-dom@18.3.1
| `-- react@18.3.1 deduped
`-- react@18.3.1
라이브러리(예: UI 컴포넌트, 플러그인)에서 이 오류가 나면, 그 라이브러리의 새 버전이 내 react 버전을 지원하는지 npm view 패키지이름 peerDependencies로 확인하고 버전을 올리는 게 정석입니다.
3. 해결 2: --legacy-peer-deps (급할 때만)
npm i react-dom@17.0.2 --legacy-peer-deps
npm 6처럼 peer dependency 검사를 건너뛰고 설치합니다. 직접 해 보니 added 3 packages로 설치가 끝났고, npm ls만 치면 오류 없이 아래처럼 보였습니다.
+-- react-dom@17.0.2
`-- react@18.3.1
하지만 npm ls react react-dom으로 확인하면 문제가 그대로 드러납니다.
| `-- react@18.3.1 deduped invalid: "17.0.2" from node_modules/react-dom
npm error code ELSPROBLEMS
이 옵션으로 설치했다면 꼭 이 명령으로 한 번 확인하세요.
즉 react 18과 react-dom 17이 섞인 상태 그대로입니다. 실행할 때 오류가 날 수 있으니, 빌드·실행까지 꼭 확인해야 합니다. 팀 프로젝트라면 다른 사람도 같은 옵션이 필요해지므로 .npmrc에 legacy-peer-deps=true를 넣는 방식은 신중하게 쓰세요.
4. 해결 3: --force (권하지 않음)
npm i react-dom@17.0.2 --force
npm warn using --force Recommended protections disabled.
npm warn ERESOLVE overriding peer dependency
경고를 내고 충돌을 무시한 채 설치합니다. 메시지 그대로 "보호 장치를 끈" 상태라, 원인을 모를 때 쓰면 나중에 더 찾기 어려운 오류로 돌아옵니다.
5. 자주 나오는 상황
- 오래된 튜토리얼을 따라 할 때: 튜토리얼은 react 17 기준인데 새 프로젝트는 react 18 이상인 경우. 튜토리얼의 패키지 버전을 그대로 쓰기보다 최신 버전을 설치하는 편이 낫습니다.
- package-lock.json이 오래됐을 때: 버전을 맞췄는데도 계속 나면
node_modules와package-lock.json을 지우고 다시npm install해 보세요(지우기 전에 git 커밋을 해 두면 되돌리기 쉽습니다).
6. 한눈에 정리
| 방법 | 명령 | 판단 |
|---|---|---|
| 요구 버전 확인 | npm view 패키지 peerDependencies |
먼저 할 일 |
| 버전 맞추기 | npm i 패키지@맞는버전 |
추천 |
| 검사 건너뛰기 | --legacy-peer-deps |
급할 때, 실행 확인 필수 |
| 강제 설치 | --force |
비추천 |
실행 환경: 리눅스, Node.js v22.23.4, npm 10.9.9. 윈도우·맥에서는 직접 실행하지 않았습니다. 초안 작성과 검수에 AI를 사용했고, 명령과 출력은 직접 실행해 대조했습니다.
기준일: 2026-11-20
출처
- npm 설정 문서 (legacy-peer-deps, force): https://docs.npmjs.com/cli/v10/using-npm/config
- npm install 문서: https://docs.npmjs.com/cli/v10/commands/npm-install