npm & Package Management

npm is three things with one name: the public registry at registry.npmjs.org, the npm command line client, and the package.json / package-lock.json file formats that describe a project and its dependency tree. The client is written in JavaScript and runs on top of Node.js; the Node.js installers and release archives include a copy of it (see Installing Node.js). The Learn article introduces npm install, the --save-dev, --no-save and --save-optional flags and npm run; this page goes further. The article also notes that Yarn and pnpm are alternatives to the npm client; they read the same registry. The Workspaces & Publishing page compares them and covers monorepos.

The release lines and their end-of-life dates are explained in Release Lines & LTS. To see which npm you are running, and to try npm 12 without changing the npm that came with Node.js, install it into a throwaway directory and run its binary from there (a global update with npm install -g npm@12 works too; npm itself prints that hint when a newer version exists).

Source: Node.js Learn: An introduction to the npm package manager

On Node.js 26.10.0 this printed v26.10.0, 11.19.1 and 12.2.0; on Node.js 24.21.0 and 22.23.3 the middle line was 11.19.0 and 10.9.9. Every "npm 12" example below uses that locally installed binary (written npm12 in the prose).

Most of the daily commands are verbs on the dependency tree. The tables and transcripts below come from a small scratch project; paths are shortened. Every command runs unchanged on npm 10, 11 and 12 unless stated.

Semantic versioning (SemVer) gives the three numbers meaning: increment the first (MAJOR) for breaking changes, the middle (MINOR) for backward-compatible features and the last (PATCH) for backward-compatible fixes. A range in package.json is a promise about which of those you accept automatically. The npm documentation lists the common forms: patch releases 1.0, 1.0.x or ~1.0.4; minor releases 1, 1.x or ^1.0.4; and any release * or x.

Source: npm Docs: About semantic versioning

The output is identical on Node.js 26, 24 and 22. Three rules are worth memorising. The caret ^ allows everything that does not change the left-most non-zero digit, so ^0.2.3 stays inside 0.2.x and ^0.0.3 accepts only 0.0.3: before the first stable release, every minor release may break. The tilde ~ allows patch releases only. A prerelease such as 2.0.1-beta.1 does not match a plain range like >=1.0.0; it matches only a range that names a prerelease on the same major.minor.patch, so * and ^ do not pull betas by accident. Remember that the range only describes what may be installed: the lockfile decides what is.

Two settings change what npm install <pkg> saves. --save-exact (-E) writes the exact version, and --save-prefix='~' writes a tilde range; both can be made permanent in a project .npmrc with npm config set save-exact true --location=project. The scratch run produced these entries on npm 11.19.1, 11.19.0 and 10.9.9:

Source: npm Docs: npm install, save-exact and save-prefix

Exact pins give reproducibility for the one package you pinned, but not for its transitive dependencies; only the lockfile fixes the whole tree. Pin directly when a tool must not move without review (formatters and code generators are typical), and let the lockfile plus a regular npm outdated review handle the rest.

package-lock.json is written automatically whenever npm changes node_modules or package.json. It records the exact tree: every package location, version, registry URL (resolved), content hash (integrity) and whether it is a development or optional dependency. Commit it for every application. lockfileVersion: 3 is what npm 9 and later write, and what the scratch run produced. The excerpt below is the entry for one package (the hash is shortened):

Source: npm Docs: package-lock.json

npm install treats the lockfile as a starting point: it may update it when package.json asks for something the lock does not satisfy. npm ci ("clean install", aliases clean-install, ic) treats it as a contract. It requires a lockfile, fails instead of changing it when package.json disagrees, deletes any existing node_modules first, can only install the whole project, and never writes package.json or package-lock.json. That is what you want in CI, in Docker builds and on deployment machines.

Source: npm Docs: npm ci

The first call installed all three packages, the second --omit=dev installed only the two production ones (the development dependency prettier is gone), and the last call failed with exit code 1 because the edited range no longer matched the lock. The same output was produced on Node.js 24 and 22. The --omit=dev flag is the current way to leave out development dependencies; the older --production flag and --only=prod are documented as deprecated aliases for it. A Dockerfile therefore installs with npm ci --omit=dev, as shown in Docker & Containers. If you generate the lockfile with flags that change the tree shape, such as --legacy-peer-deps, pass the same flags to npm ci, or store them in the project .npmrc.

npm ci also fixes the order in which scripts run, which matters for the Scripts: lifecycle, pre and post, --, .bin section: preinstall runs after the lockfile has been validated but before dependencies are fetched, so it cannot rely on anything in node_modules. Two more facts about lockfiles: node_modules/.package-lock.json is a "hidden lockfile" npm uses to avoid rescanning the folder (never commit it), and as of npm 12 the file npm-shrinkwrap.json is no longer read or written (rename it to package-lock.json; a dependency that ships one inside its tarball has it ignored, so publishers who need to ship a locked tree use bundleDependencies).

package.json has several dependency maps, and the map decides when a package is installed and who is responsible for it. The full file reference is the subject of package.json, exports & imports.

Source: npm Docs: package.json

When two packages need incompatible versions of a third, npm installs both in nested node_modules folders. When you must change what is installed deep in the tree, for instance to apply a security fix before the intermediate package releases one, use overrides. It is honoured only in the root package.json of the project; overrides inside installed dependencies and workspaces are ignored.

Source: npm Docs: package.json, overrides

The first npm ls shows the version that is-odd asked for; after the override, the same position is 7.0.0 and npm ls marks it overridden. An override can be a bare version (applies everywhere), a nested object ({ "is-odd": { "is-number": "6.0.0" } } applies only below is-odd), a semver range, a dist-tag or a replacement spec such as npm: or file:. Overrides are an escape hatch: they can pick a version the consuming package was never tested with, so remove them once the real dependency catches up. Run npm explain <name> to see which override applies.

The scripts field maps names to shell commands. npm run <name> runs one; npm start, npm test, npm stop and npm restart are shortcuts for the built-in names, and npm run with no name lists everything. npm runs the command through /bin/sh on POSIX systems and cmd.exe on Windows (configurable with script-shell), always from the package root, with an environment that includes npm_package_name, npm_package_version, npm_lifecycle_event and npm_package_json. Since npm 7 most other package.json fields are no longer exported as variables; read the file or use npm_package_json.

Source: npm Docs: Scripts

Two behaviours are visible in this file. Any script x can have prex and postx companions, which npm runs automatically around it: npm run build printed prebuild, build, postbuild in that order, and npm test ran pretest, the tests, then posttest. And fmt calls prettier with no path: npm adds the project’s node_modules/.bin (and those of parent folders) to PATH for the script, so the locally installed version runs (3.3.3), whatever is or is not installed globally. That is why scripts, not global tools, are the way to share commands in a repository.

Source: npm Docs: npm run

Source: npm Docs: npm run

Everything after a lone -- goes to the script; without it npm treats --port as its own option and passes only the non-option 3000. On Node.js 26, 24 and 22 (npm 11 and 10) the second form also printed a warning that --port is an unknown cli config that "will stop working in the next major version of npm", and npm 12 is that major version: it fails with EUNKNOWNCONFIG and Unknown cli flag: --port. Always write the --. The same npm 12 release turned unknown keys in .npmrc, abbreviated flags and single-hyphen multi-character shorthands into errors, so a typo is no longer silently ignored. For running a script without npm at all, see node --run in Running Scripts, the CLI & the REPL; it runs the same scripts entries, adds node_modules/.bin to the path, but does not run pre and post companions.

npx runs a command from an npm package: one installed in the project, or one fetched on demand into the npm cache. It shares its implementation with npm exec (since npm 7). Local executables win: with semver installed as a dependency, npx semver uses that copy; otherwise the package is downloaded and a prompt asks first (suppress it with --yes or --no).

Source: npm Docs: npx

The first command printed 1.2.3 (the version satisfies the range), the second printed nothing and exited with code 1, the third printed 1.3.0, the fourth 1.2.4, and the last printed the help of SemVer 6.3.1 rather than the 7.x copy: a package name with a specifier only counts as the local one when name and version match exactly. When no prompt can be shown (no terminal), npm 11 printed a warning that the package "was not found and will be installed" and went ahead, so be careful in scripts that call npx on unreviewed names: that is a way to run code you have not locked in package-lock.json. The option rule from the npm documentation: with npx, all flags must come before the first positional argument; with npm exec, use -- to separate npm’s flags from the command’s. In a real terminal, name the package and its version explicitly (npx --yes semver@7.8.5) when the command must be reproducible.

npm audit submits a description of the dependencies configured in your project to the registry and prints the report of known vulnerabilities it gets back. npm audit fix applies compatible updates, --audit-level=<level> sets the minimum severity that makes the exit code non-zero, and --omit=dev limits the report to what production installs. npm audit signatures verifies the registry signatures of the installed tarballs.

Source: npm Docs: npm audit

npm audit exited with code 1 (it does whenever a vulnerability is found, as the documentation says), npm audit fix moved minimist to 1.2.8 within its range, and the signature check passed. The output is a point-in-time snapshot of the advisory database, so yours will differ. Audit is a floor, not a guarantee: it knows only published advisories, says nothing about malicious packages published yesterday, and complains about development dependencies that never reach production (use --omit=dev). The wider threat model (typosquatting, dependency confusion, compromised maintainers) and what to do about it is the topic of Security Best Practices. The npm threats-and-mitigations page is the official companion. Combine five habits: commit and review the lockfile, install with npm ci, keep the tree small, apply the npm 12 script policy below, and consider a release-age cool-down (also below).

A local install puts packages in the project’s node_modules and lists them in package.json; anything the application imports or runs belongs there. A global install (-g) puts a package in the folder of the current Node.js installation and exists to put a command on your PATH. Because the global folder is per Node.js installation, switching versions with a version manager such as nvm gives you a different set of global packages; the Installing Node.js page covers the managers.

Source: npm Docs: folders

On the scratch machine the local root was the project’s node_modules, the global root was <prefix>/lib/node_modules under the active Node.js installation, and the global list contained only npm@11.19.1. Prefer local installs and npm exec or npx for tools: the version is recorded in package.json and the lockfile, so everyone, including CI, uses the same one. Reserve global installs for tools that are not tied to a project, and note that npm 12 asks you to provide install-script permissions for global installs and npx through the --allow-scripts flag, because there is no project package.json in which to record them (npm 12 and the supply-chain changes). On Unix-like systems, do not use sudo npm install -g: install Node.js with a version manager or into a user-owned prefix instead.

npm 12.0.0 (2026-07-08) is a major release with defaults aimed at supply-chain attacks. The 12.0.0 release notes list the breaking changes verified here by running npm 12.2.0 on Node.js 26.10.0:

Source: npm Docs: Changelog (12.0.0, breaking changes), npm Docs: config (allow-git, allow-remote), npm CLI release notes on GitHub: v12.0.0

Source: npm Docs: Changelog (11.10.0 to 12.2.0), npm CLI release notes on GitHub: v12.0.0

Earlier changes still worth knowing: the --production flag is deprecated in favour of --omit=dev; npm 7 made peerDependencies install automatically and introduced lockfile version 2 and the hidden lockfile; npm 9 introduced lockfileVersion: 3. Corepack is no longer part of the Node.js distribution (see Installing Node.js), so pnpm and Yarn are installed like any other tool.

Efficient Node.js (Samer Buna, O’Reilly 2025) has a chapter on package management covering npm show, ls, link, cache, the install forms, SemVer operators, --save-exact, update, outdated, prune, the lockfile, scripts and npx. Its baseline is Node.js 22 with npm 10, so the concepts hold but three points need updating: use npm ci and --omit=dev where an older workflow runs prune and install before tests or deploys, treat --production as deprecated, and read the install section knowing that npm 12 blocks dependency scripts, refuses git and URL dependencies by default and errors on unknown flags. Nothing in it covers allowScripts, npm install-scripts or min-release-age, which did not exist in npm 10.

Node.js Projects (Jonathan Wexler, O’Reilly 2025) uses npm init, package.json fields, SemVer ranges and, in its appendices, Yarn and Corepack. The npm usage is still valid; the Corepack route is not, because Corepack is no longer bundled with current Node.js. Its projects also install packages such as dotenv, nodemon and npm-run-all, for which Node.js now has built-ins (--env-file, --watch and node --run, covered in CLI Options, Environment & Config File), and a native add-on installed from npm would need an allowScripts entry on npm 12. Both books were written before npm 12, so neither explains why npm install on a fresh machine may now report blocked scripts.

For publishing a package to the registry, package.json fields such as files, exports and engines, and trusted publishing, see JavaScript Tooling: Bundling, npm & Publishing; this page deliberately covers only what that page lacks (lockfiles and npm ci, audit, npm 12, npx and overrides). The Node.js-specific publishing topics and workspaces continue in Workspaces & Publishing.