With npm, what does `npm audit fix` change in a project, what does it leave alone, and when does `--force` cross a major version?
answer
- fixes that fit the declared ranges
- a vulnerable chain up to the root
- force steps outside the range
- exit threshold, not a report filter
- preview before applying
basics
~20 snpm audit fix moves vulnerable packages to non-vulnerable versions that the declared ranges already allow. A fix that needs a range change is left alone unless you pass --force, which may install a SemVer-major update of a direct dependency.
solid answer
~40 s`npm audit` sends the tree recorded in `package-lock.json` to the registry and reports advisories, including meta-vulnerabilities: packages vulnerable only because they depend on a vulnerable range. `npm audit fix` runs a full install that moves vulnerable packages to versions without an advisory, as long as no dependency range has to change, which covers most transitive patches. When the vulnerable chain reaches the root and only a newer major of a direct dependency escapes it, plain `fix` leaves it in place and `--force` applies it, installing outside your stated range, possibly a breaking major. Preview with `npm audit fix --dry-run --json`. In CI, `npm audit --audit-level=high` sets the failure threshold without filtering what the report shows.
code
bash · 4 linesnpm audit --audit-level=high # CI gate: fail only on high or critical
npm audit fix --dry-run --json # preview what a fix would change
npm audit fix --package-lock-only # apply in-range fixes to the lock for review
npm audit fix --force # also change ranges; may install a new majorgo deeper
Recall that npm audit reports known vulnerabilities in the locked tree and npm audit fix applies the updates that fit your declared ranges.
Explain the boundary: in-range fixes are applied, fixes that need a range change wait for --force, and audit-level only sets the exit threshold.
Show you never run --force blind: preview with --dry-run, upgrade breaking majors deliberately with tests, and gate CI on a chosen severity.
Set the policy for which severities block a merge and who owns forced upgrades, balancing patch latency against the cost of breaking changes.
## What `npm audit` sends and reports `npm audit` describes the project's dependency tree to the configured registry and asks for known vulnerabilities. By default it needs a `package-lock.json`, because it audits the tree the lock records; `--no-package-lock` audits a freshly built tree instead, and the results can then vary from run to run. Packages excluded with `--omit` (for example `--omit=dev`) are left out of what is submitted. Plain `npm install` also submits an audit by default, which is where the "found N vulnerabilities" line after an install comes from. The report covers two kinds of finding: - a **vulnerability**, a package version inside an advisory's vulnerable range; - a **meta-vulnerability**, a package that is vulnerable only because the range it declares can only be met by vulnerable versions of something else. ## What `npm audit fix` changes `npm audit fix` turns the report into changes by running a full `npm install` underneath, so every installer setting applies to it. It: - moves each vulnerable package, direct or transitive, to a version with no advisory or meta-vulnerability posted against it, **provided no dependency range has to change**; - updates `node_modules` and `package-lock.json` (with `--package-lock-only`, only the lock); - leaves alone anything it cannot fix inside existing ranges, and anything with no fixed version at all, which needs manual work. ## When `--force` is needed npm's own example shows the boundary: 1. `chrono-fmt` is vulnerable in `>=1.0.2 <2.0.0`; the fix is `2.x`. 2. `route-map-kit@5` depends on `chrono-fmt@^1.1.0`, so every version of it that satisfies its range is vulnerable, which makes `route-map-kit` a meta-vulnerability. 3. The chain reaches the root: the project declares `route-map-kit@^5`, and only `route-map-kit@6` depends on a fixed `chrono-fmt`. 4. Reaching `6` means changing the project's dependency range. Plain `npm audit fix` will not do that; `npm audit fix --force` will. `--force` allows `npm audit fix` to install modules outside your stated dependency range, including SemVer-major changes. That is exactly a breaking upgrade, chosen by a tool, applied to every remediation that needs it at once. | Command | Effect | |---|---| | `npm audit` | reports; exits non-zero if any vulnerability is found | | `npm audit --audit-level=high` | same report; exits non-zero only for `high` or `critical` | | `npm audit fix` | applies in-range fixes to `node_modules` and the lock | | `npm audit fix --package-lock-only` | applies in-range fixes to the lock only | | `npm audit fix --dry-run --json` | shows what would change, applies nothing | | `npm audit fix --force` | also applies fixes that change ranges, including new majors | ## Running it in CI - **Gate on a threshold.** `--audit-level` takes `info`, `low`, `moderate`, `high`, `critical` or `none`. It changes only the failure threshold; the report still lists everything. - **Keep fixes reviewable.** Run `npm audit fix` (or `--package-lock-only`) on a branch so the lock diff is reviewed and `npm ci` verifies it, rather than fixing inside the build. - **Never `--force` blind.** Preview with `--dry-run`, then upgrade the risky direct dependency deliberately and run its tests. - **Scope the gate if that is the policy.** `npm audit --omit=dev` leaves development-only packages out of the submitted tree, for teams that only gate on what ships. - **Read the exit code of `fix` too.** `npm audit fix` exits 0 only when nothing was found or every finding was fixed; whatever remains is judged against `audit-level`, so a job that runs `fix` can still fail on what it could not repair. ## What it cannot do Some findings stay after every safe fix: no patched version exists, or the only route crosses a major you are not ready for. The options are then upgrading the direct dependency yourself, pinning a transitive version with an `overrides` entry in the root `package.json`, or recording an accepted risk. Which advisory sources the registry draws on, and why scanners disagree, is a separate question from these commands.
- How do you turn audit fixes into a reviewable pull request without touching `node_modules`?Run `npm audit fix --package-lock-only`. Because `audit fix` is a full install underneath, installer settings apply to it, and this one updates `package-lock.json` without changing `node_modules`. The lock diff then goes through review and `npm ci` like any other dependency change.
- Does `--audit-level=high` hide low-severity findings from the report?No. It only sets the lowest severity that makes the command exit non-zero; the report still lists every finding. A pipeline can fail on high and critical issues while engineers still see the moderate and low ones in the output.
- Why can `--force` be acceptable for one project and dangerous for another?`--force` applies every remediation that needs a range change, not just the one you are looking at. If the only forced change is a direct dependency whose new major you have read and tested, it is a normal upgrade done by a tool. If it also moves a framework or build tool across a major, it is an untested breaking change, so preview with `--dry-run` first.
- npm audit fix only edits package-lock.json and never touches node_modules.
- npm audit fix will move a direct dependency to a new major whenever needed.
- audit-level filters low findings out of the npm audit report.
- npm audit fix --force only changes the one package you were worried about.
- npm audit works the same with no lockfile at all.