npm: When to use `--force` and `--legacy-peer-deps`

Question

I'm trying to understand how recreating the node_modules directory for deployment works.

We're using npm ci instead of npm install to ensure a clean slate during deployment. However, when we run it without any flags, we get the following error:

Fix the upstream dependency conflict, or retry this command with --force, or --legacy-peer-deps to accept an incorrect (and potentially broken) dependency resolution.

The documentation for npm install for --force is as follows (there are no flags on npm ci's page):

The -f or --force argument will force npm to fetch remote resources even if a local copy exists on disk.

Meanwhile, the documentation for --legacy-peer-deps says:

--legacy-peer-deps: ignore all peerDependencies when installing, in the style of npm version 4 through version 6.

It seems that both flags will let npm ci generate the node_modules directory without any issues, but I am still unclear about the differences between the two.

From what I understand, --force sounds like it will be on a last-dependency-downloaded-wins basis and will overwrite any previously downloaded dependencies. Meanwhile, --legacy-peer-deps sounds like it will always skip peer dependencies (whatever those are) during installation even if there are no issues.

What are the differences between the two flags, and when should we use them?

score 164 · Accepted Answer · edited May 16 '22 at 10:11

164

In the new version of npm (v7), by default, npm install will fail when it encounters conflicting peerDependencies. It was not like that before.

Take a look here for more info about peer dependencies in npm v7.

The differences between the two are below -

--legacy-peer-deps: ignore all peerDependencies when installing, in the style of npm version 4 through version 6.
--strict-peer-deps: fail and abort the install process for any conflicting peerDependencies when encountered. By default, npm will only crash for peerDependencies conflicts caused by the direct dependencies of the root project.
--force: will force npm to fetch remote resources even if a local copy exists on disk.

edited May 16 '22 at 10:11

Kostas Minaidis

4,681
3
17
25

answered Feb 03 '21 at 21:09

Eduardo Almeida

1,800
1
5
3

46

and what of `--force` per OP? Are there performance benefits with one over the other or overall deduped packages, etc? – jflay Feb 09 '21 at 22:15
1

`--force` still pins many dependency versions while `--legacy-peer-deps` ignore peer dependencies entirely. See example from @HongboMiao – Ogglas Jun 14 '22 at 09:04
11

The question is about the when to use what but I don't see that in the answer. Can you elaborate more about what are the differences between the 2? – Cupid Chan Jun 17 '22 at 10:29

score 80 · Answer 2 · edited Aug 20 '22 at 12:01

In the article npm 7 is now generally available!,

You have the option to retry with --force to bypass the conflict or --legacy-peer-deps command to ignore peer dependencies entirely (this behavior is similar to versions 4-6).

I agree this sentence is not really clear, but "ignore peer dependencies entirely" does not sound good. Let's use a real example:

Here is a peer dependency error I met when I npm install:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: mobile@undefined
npm ERR! Found: react@17.0.1
npm ERR! node_modules/react
npm ERR!   react@"17.0.1" from the root project
npm ERR!   peer react@">=16.0.0" from @testing-library/react-native@7.2.0
npm ERR!   node_modules/@testing-library/react-native
npm ERR!     dev @testing-library/react-native@"7.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"16.13.1" from react-native@0.63.2
npm ERR! node_modules/react-native
npm ERR!   react-native@"https://github.com/expo/react-native/archive/sdk-39.0.4.tar.gz" from the root project
npm ERR!   peer react-native@">=0.59" from @testing-library/react-native@7.2.0
npm ERR!   node_modules/@testing-library/react-native
npm ERR!     dev @testing-library/react-native@"7.2.0" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR!
npm ERR! See /Users/me/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/me/.npm/_logs/2021-03-13T00_10_33_813Z-debug.log
npm ERR! code 1
npm ERR! path /Users/me/my-app
npm ERR! command failed
npm ERR! command sh -c sh ./bin/setup.sh

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/me/.npm/_logs/2021-03-13T00_10_33_860Z-debug.log

Below is the package-lock.json difference between --legacy-peer-deps and --force.

If I run npm install --legacy-peer-deps, it adds this in my package-lock.json:

"node_modules/@unimodules/react-native-adapter": {
  "version": "5.7.0",
  "resolved": "https://registry.npmjs.org/@unimodules/react-native-adapter/-/react-native-adapter-5.7.0.tgz",
  "integrity": "sha512-L557/+sc8ZKJVgo1734HF1QNCxrt/fpqdmdNgySJT+kErux/AJNfPq3flsK0fyJduVmniTutYIMyW48cFoPKDA==",
  "dependencies": {
    "invariant": "^2.2.4",
    "lodash": "^4.5.0"
  },
  "peerDependencies": {
    "react-native": "*",
    "react-native-web": "~0.13.7"
  }
},

...

"@unimodules/react-native-adapter": {
  "version": "5.7.0",
  "resolved": "https://registry.npmjs.org/@unimodules/react-native-adapter/-/react-native-adapter-5.7.0.tgz",
  "integrity": "sha512-L557/+sc8ZKJVgo1734HF1QNCxrt/fpqdmdNgySJT+kErux/AJNfPq3flsK0fyJduVmniTutYIMyW48cFoPKDA==",
  "requires": {
    "invariant": "^2.2.4",
    "lodash": "^4.5.0"
  }
},

If I use npm install --force, instead, it adds

"node_modules/expo/node_modules/@unimodules/react-native-adapter": {
  "version": "5.7.0",
  "resolved": "https://registry.npmjs.org/@unimodules/react-native-adapter/-/react-native-adapter-5.7.0.tgz",
  "integrity": "sha512-L557/+sc8ZKJVgo1734HF1QNCxrt/fpqdmdNgySJT+kErux/AJNfPq3flsK0fyJduVmniTutYIMyW48cFoPKDA==",
  "dependencies": {
    "invariant": "^2.2.4",
    "lodash": "^4.5.0"
  },
  "peerDependencies": {
    "react-native": "*",
    "react-native-web": "~0.13.7"
  }
},
"node_modules/expo/node_modules/inline-style-prefixer": {
  "version": "5.1.2",
  "resolved": "https://registry.npmjs.org/inline-style-prefixer/-/inline-style-prefixer-5.1.2.tgz",
  "integrity": "sha512-PYUF+94gDfhy+LsQxM0g3d6Hge4l1pAqOSOiZuHWzMvQEGsbRQ/ck2WioLqrY2ZkHyPgVUXxn+hrkF7D6QUGbA==",
  "peer": true,
  "dependencies": {
    "css-in-js-utils": "^2.0.0"
  }
},
"node_modules/expo/node_modules/react-native-web": {
  "version": "0.13.18",
  "resolved": "https://registry.npmjs.org/react-native-web/-/react-native-web-0.13.18.tgz",
  "integrity": "sha512-WR/0ECAmwLQ2+2cL2Ur+0/swXFAtcSM0URoADJmG6D4MnY+wGc91JO8LoOTlgY0USBOY+qG/beRrjFa+RAuOiA==",
  "peer": true,
  "dependencies": {
    "array-find-index": "^1.0.2",
    "create-react-class": "^15.6.2",
    "deep-assign": "^3.0.0",
    "fbjs": "^1.0.0",
    "hyphenate-style-name": "^1.0.3",
    "inline-style-prefixer": "^5.1.0",
    "normalize-css-color": "^1.0.2",
    "prop-types": "^15.6.0",
    "react-timer-mixin": "^0.13.4"
  },
  "peerDependencies": {
    "react": ">=16.5.1",
    "react-dom": ">=16.5.1"
  }
},

...

  "dependencies": {
    "@unimodules/react-native-adapter": {
      "version": "5.7.0",
      "resolved": "https://registry.npmjs.org/@unimodules/react-native-adapter/-/react-native-adapter-5.7.0.tgz",
      "integrity": "sha512-L557/+sc8ZKJVgo1734HF1QNCxrt/fpqdmdNgySJT+kErux/AJNfPq3flsK0fyJduVmniTutYIMyW48cFoPKDA==",
      "requires": {
        "invariant": "^2.2.4",
        "lodash": "^4.5.0"
      }
    },
    "inline-style-prefixer": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/inline-style-prefixer/-/inline-style-prefixer-5.1.2.tgz",
      "integrity": "sha512-PYUF+94gDfhy+LsQxM0g3d6Hge4l1pAqOSOiZuHWzMvQEGsbRQ/ck2WioLqrY2ZkHyPgVUXxn+hrkF7D6QUGbA==",
      "peer": true,
      "requires": {
        "css-in-js-utils": "^2.0.0"
      }
    },
    "react-native-web": {
      "version": "0.13.18",
      "resolved": "https://registry.npmjs.org/react-native-web/-/react-native-web-0.13.18.tgz",
      "integrity": "sha512-WR/0ECAmwLQ2+2cL2Ur+0/swXFAtcSM0URoADJmG6D4MnY+wGc91JO8LoOTlgY0USBOY+qG/beRrjFa+RAuOiA==",
      "peer": true,
      "requires": {
        "array-find-index": "^1.0.2",
        "create-react-class": "^15.6.2",
        "deep-assign": "^3.0.0",
        "fbjs": "^1.0.0",
        "hyphenate-style-name": "^1.0.3",
        "inline-style-prefixer": "^5.1.0",
        "normalize-css-color": "^1.0.2",
        "prop-types": "^15.6.0",
        "react-timer-mixin": "^0.13.4"
      }
    }
  }
},

As you see, npm install --force still pins many dependency versions which is stricter.

When I'm using `yarn` instead of `npm install` it does not seem to get any errors and it installs the packages without prompting any errors? Is there any problem using `yarn` instead of `npm`? — Emad Baqeri, Oct 22 '21 at 15:46
I don't quite understand, with `--legacy-peer-deps` it just doesn't install any of the peer dependencies? — Plumpie, Nov 23 '21 at 11:00
@Plumpie Yes `--legacy-peer-deps` ignores peer dependencies entirely which may result in an incorrect/broken dependency resolution. — Dillon, Apr 28 '22 at 15:28
@Dillon so if I ignore peer dependencies entirely, the peer dependencies won't be installed automatically. That must mean that almost every package that has peerDependencies should not work correctly, because it relies on peer packages that are not installed. Am I right? — Dominik R., Jun 13 '23 at 12:19

score 26 · Answer 3 · answered Nov 13 '22 at 06:35

For those wondering which is safer, the answer is --force

--legacy-peer-deps ignores peer dependencies entirely, which can screw up your dependency resolution.

--force on the other hand simply sets a different peer dependency version for conflicting dependencies

Using force isn't always ideal though because each dependency version takes up extra space. Using force with many dependencies will increase your total space requirement a decent amount.

Jyoti Duhan · Answer 4 · 2023-03-08T09:50:12.370

-1

If you want a temporary workaround to get rid of npm peer dependency errors or ignore peer-dependencies, use --legacy-peer-deps but to set a different peer dependency tree than the conflicting one, use --force. Find more info here

edited Mar 08 '23 at 09:50

answered Mar 08 '23 at 09:34

Jyoti Duhan

988
1
16
26

npm: When to use `--force` and `--legacy-peer-deps`

4 Answers4

Linked

Related