npm

Also known as: Node Package Manager

On this page 7

npm is the default package manager for Node.js, consisting of a command-line client, a public package registry and a manifest format that together let developers install, version and publish reusable JavaScript code. In programming, it is one of the most widely used development tools, because almost every JavaScript project, whether a browser application, a server or a command-line utility, declares its dependencies through npm.

The name originally expanded to Node Package Manager, although the project now treats “npm” as a lowercase name rather than an acronym. It ships with every standard Node.js installation, and its registry hosts millions of packages, which makes it the largest software registry for any single language ecosystem.

How npm resolves and installs packages

npm installs packages by reading a project manifest, resolving a dependency tree that satisfies every declared version range, downloading tarballs from the registry and writing them into a local node_modules directory. The manifest is package.json, which lists the project name, version, scripts and the packages it needs.

Because dependencies have their own dependencies, a project with ten direct packages can easily pull in hundreds of transitive packages. npm uses a flattened, hoisted layout since version 3: it places shared packages at the top of node_modules when versions are compatible and nests a separate copy only when two packages require conflicting version ranges. The Node.js module resolver then walks up the directory tree to find each import.

The resolved result is recorded in package-lock.json, the lockfile, which pins the exact version, download location and integrity hash of every package. The following table summarizes the files and directories that npm creates and reads.

File or directoryPurposeCommit to version control
package.jsonDeclares metadata, scripts and version rangesYes
package-lock.jsonPins the exact resolved tree and hashesYes
node_modulesHolds the installed package filesNo
.npmrcConfigures registry, authentication and optionsYes, without secrets
Core files in an npm project

Semantic versioning and dependency types

npm relies on semantic versioning (SemVer), in which a version such as 4.17.21 means major, minor and patch. A major increase signals breaking changes, a minor increase adds compatible features and a patch fixes bugs. Version ranges in package.json tell npm how much drift a project accepts.

The caret range (^1.4.0) is the default written by npm install, and it accepts any 1.x release at or above 1.4.0. This default favors receiving fixes automatically, but it also means that a fresh install without a lockfile can produce a different tree from one week to the next.

RangeAccepted versionsTypical use
^1.4.01.4.0 up to, not including, 2.0.0Default for most dependencies
~1.4.01.4.0 up to, not including, 1.5.0Patch updates only
1.4.0Exactly 1.4.0Strict pinning of sensitive packages
>=1.4.0 <3.0.0Any version in the explicit intervalLibraries supporting several majors
Common version range notations

npm also distinguishes dependency categories in the manifest. dependencies are needed at run time, devDependencies are needed only for building and testing, peerDependencies declare a package that the host project must supply, such as a framework for a plugin, and optionalDependencies may fail to install without stopping the process. Since npm 7, peer dependencies are installed automatically, which surfaces version conflicts that earlier versions only reported as warnings.

Essential npm commands and scripts

Day-to-day work with npm uses a small set of commands, and the most important distinction is between npm install and npm ci. The first may update the lockfile when package.json changes, while the second installs exactly what the lockfile specifies and fails if the two files disagree, which makes it the correct choice for continuous integration.

CommandWhat it doesWhen to use it
npm installInstalls dependencies and may update the lockfileLocal development
npm ciDeletes node_modules and installs from the lockfileBuild servers and reproducible builds
npm run nameRuns a script defined in package.jsonBuilds, tests and linting
npm auditChecks the tree against known vulnerabilitiesRegular security review
npm outdatedLists packages with newer versionsPlanning upgrades
npm publishUploads a package to the registryReleasing a library
Frequently used npm commands

The scripts field turns npm into a lightweight task runner. A project typically defines build, test and lint scripts, and npm adds node_modules/.bin to the path so that locally installed tools such as a linter or a bundler run without global installation. The companion tool npx executes a package binary directly, downloading it temporarily when it is not installed.

npm compared with other JavaScript package managers

npm is the baseline package manager, but Yarn, pnpm and Bun offer alternative clients that use the same public registry and the same package.json format. They differ mainly in installation speed, disk usage and how strictly they isolate dependencies.

ClientInstallation layoutMain strengthMain trade-off
npmFlattened node_modulesBundled with Node.js, widest compatibilityAllows phantom dependencies
YarnFlattened or Plug’n’PlayMature workspaces and offline cachePlug’n’Play needs tool support
pnpmContent-addressable store with linksSaves disk space, strict isolationSome tools assume a flat tree
BunFlattened node_modulesVery fast installationYounger ecosystem and runtime
npm and alternative clients

A phantom dependency is a package that code imports without declaring it, which works only because hoisting happened to place it at the top level. pnpm prevents this by design; with npm, the safeguard is a linter rule or careful review. Since npm 7, the client also supports workspaces, which manage several packages in one repository with a single lockfile.

Security risks and common mistakes with npm

The main risk of npm is the software supply chain: every installed package can run code on the developer machine and in production. Install-time lifecycle scripts such as postinstall execute automatically, which attackers have exploited through typosquatting, hijacked maintainer accounts and malicious updates to popular packages.

Effective defenses include two-factor authentication for publishers, provenance attestations that link a published package to its source build, npm ci with a committed lockfile and periodic npm audit runs. Teams that need stricter control can set ignore-scripts=true and use a private registry mirror that only serves approved packages.

SymptomLikely causeFix
Build works locally but fails in CILockfile missing or out of dateCommit the lockfile and use npm ci
ERESOLVE peer dependency errorIncompatible peer version rangesAlign versions rather than forcing installs
Huge node_modules directoryMany transitive dependenciesRemove unused packages and review additions
Audit reports many warningsVulnerable transitive packagesUpdate parents or apply overrides
Typical npm problems and fixes

A frequent mistake is using --force or --legacy-peer-deps as a permanent workaround, which hides real incompatibilities. Another is treating every audit warning as critical; many concern development-only tools, so triage by actual exposure matters more than reaching zero warnings.

In plain words

npm is like an app store and a shopping list for JavaScript code. Instead of writing everything from scratch, a developer writes a list of ready-made building blocks the project needs, and npm fetches them from a huge shared library.

It also keeps a precise receipt of which version of every block was used. Thanks to that receipt, another developer or a build server can recreate exactly the same setup, which prevents the classic problem of software that works on one computer but not on another.

A real-world example

A team of four developers maintains a web shop front end built with a JavaScript framework. Their package.json lists about 30 direct dependencies, which expand to roughly 900 installed packages. Developers run npm install locally, while the build server runs npm ci, npm run lint, npm test and npm run build on every pull request.

One morning, builds start failing on a new laptop but not on the server. The cause is a missing lockfile change: a colleague had added a date library without committing package-lock.json. After committing it, all machines resolve the identical dependency tree. The team then enables weekly npm audit reports and requires review for any new dependency, which cuts the number of unplanned upgrade incidents and keeps the supply chain under control.