npm install --legacy-peer-deps: what it does and when to use it

npm install --legacy-peer-deps tells npm to ignore peerDependencies completely: it neither installs them automatically nor fails when they conflict. This restores the npm 6 behaviour and makes an ERESOLVE error go away, but the conflict is still there.

Before and after

The same conflicting install, with the flag:

npm init -y >/dev/null
npm install --no-audit --no-fund --legacy-peer-deps react@18.3.1 react-dom@19.0.0
npm ls react react-dom

added 5 packages in 4s
work@1.0.0 /tmp/work
├─┬ react-dom@19.0.0
│ └── react@18.3.1 deduped invalid: "^19.0.0" from node_modules/react-dom
└── react@18.3.1 invalid: "^19.0.0" from node_modules/react-dom

npm error code ELSPROBLEMS
npm error invalid: react@18.3.1 /tmp/work/node_modules/react
npm error A complete log of this run can be found in: /tmp/work/.npm-cache/_logs/2026-10-20T12_26_37_765Z-debug-0.log

Without the flag this install fails with ERESOLVE unable to resolve dependency tree (see the error page). With it, the install succeeds, but the tree is still wrong: npm ls marks the peer as invalid and exits with status 1, because react-dom@19.0.0 now runs against React 18, which it does not support.

Make it permanent for one project

mkdir app && cd app
npm init -y >/dev/null
npm config set legacy-peer-deps true --location project
cat .npmrc

legacy-peer-deps=true

The .npmrc file in the project root applies the setting to everyone who installs the project, including CI.

--legacy-peer-deps vs --force