npm --force vs --legacy-peer-deps

When working with npm, you may encounter peer dependency conflicts that prevent package installation. Understanding how to resolve these conflicts using --force and --legacy-peer-deps is crucial for maintaining a stable development environment.

Understanding peer dependency conflicts

Starting with npm v7, npm began enforcing stricter peer dependency checks. This means that when you run npm install or npm ci, npm will verify that all peer dependency requirements are satisfied across your dependency tree.

A typical error message looks like this:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
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.

Solution comparison

Here are the key differences between the two approaches:

Flag	Peer Dependency Checks	Other Safeguards Enforced	Impact
None	Enforced	Version resolution, lockfile consistency, integrity	Default behavior, catches all conflicts
--legacy-peer-deps	Skipped	Version resolution, lockfile consistency, integrity	Ignores only peer dependency warnings
--force	Skipped	None (all errors/warnings ignored)	Overrides all safeguards, may cause multiple package versions

When to use --legacy-peer-deps

The --legacy-peer-deps flag tells npm to ignore peer dependencies entirely, replicating the behavior of npm versions 4-6. This is generally the safer option when you need to bypass peer dependency issues.

npm install --legacy-peer-deps

Or for npm ci:

npm ci --legacy-peer-deps

This approach:

• Maintains other npm safeguards (version resolution, lockfile consistency)
• Avoids multiple versions of the same package where possible
• Is useful when packages haven't updated their peer dependencies for npm v7+

TIP

For a permanent solution, you can configure npm to always use legacy peer dependencies:

npm config set legacy-peer-deps true

When to use --force

The --force flag bypasses all safeguards, including peer dependency checks, cached packages, and version conflicts. It forces npm to fetch remote resources even if local copies exist.

npm install --force

Use --force when:

• You need to invalidate a corrupted cache
• You want to force installation despite all warnings
• You're troubleshooting and need to get a build working temporarily

WARNING

Using --force can result in:

• Multiple versions of the same package in your node_modules
• Potentially broken or non-reproducible builds
• Bloated dependency trees
• Hard-to-debug issues later

Use this option sparingly and as a last resort.

Real-world example

Consider this peer dependency conflict:

Found: react@17.0.1
Could not resolve dependency:
peer react@"16.13.1" from react-native@0.63.2

• With --legacy-peer-deps: npm installs the packages but ignores the React version conflict
• With --force: npm may install multiple React versions to satisfy all dependencies

Best practices

1. Prefer --legacy-peer-deps over --force as it maintains more safeguards
2. Address root causes by updating packages or resolving version conflicts properly
3. Use peer dependency overrides in package.json when possible (npm v8+)
4. Consider npm dedupe to clean up duplicate dependencies after using --force

INFO

npm v8+ introduced overrides, which provide a more controlled way to handle dependency conflicts without using flags.

Summary

For most peer dependency issues, --legacy-peer-deps is the safer choice as it maintains npm's other safeguards while only ignoring peer dependency requirements. Reserve --force for specific cases where you need to bypass all checks, such as cache corruption issues.

Always aim to resolve dependency conflicts properly through package updates or configuration rather than relying on these flags for long-term solutions.