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 directory | Purpose | Commit to version control |
|---|---|---|
| package.json | Declares metadata, scripts and version ranges | Yes |
| package-lock.json | Pins the exact resolved tree and hashes | Yes |
| node_modules | Holds the installed package files | No |
| .npmrc | Configures registry, authentication and options | Yes, without secrets |
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.
| Range | Accepted versions | Typical use |
|---|---|---|
| ^1.4.0 | 1.4.0 up to, not including, 2.0.0 | Default for most dependencies |
| ~1.4.0 | 1.4.0 up to, not including, 1.5.0 | Patch updates only |
| 1.4.0 | Exactly 1.4.0 | Strict pinning of sensitive packages |
| >=1.4.0 <3.0.0 | Any version in the explicit interval | Libraries supporting several majors |
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.
| Command | What it does | When to use it |
|---|---|---|
| npm install | Installs dependencies and may update the lockfile | Local development |
| npm ci | Deletes node_modules and installs from the lockfile | Build servers and reproducible builds |
| npm run name | Runs a script defined in package.json | Builds, tests and linting |
| npm audit | Checks the tree against known vulnerabilities | Regular security review |
| npm outdated | Lists packages with newer versions | Planning upgrades |
| npm publish | Uploads a package to the registry | Releasing a library |
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.
| Client | Installation layout | Main strength | Main trade-off |
|---|---|---|---|
| npm | Flattened node_modules | Bundled with Node.js, widest compatibility | Allows phantom dependencies |
| Yarn | Flattened or Plug’n’Play | Mature workspaces and offline cache | Plug’n’Play needs tool support |
| pnpm | Content-addressable store with links | Saves disk space, strict isolation | Some tools assume a flat tree |
| Bun | Flattened node_modules | Very fast installation | Younger ecosystem and runtime |
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.
| Symptom | Likely cause | Fix |
|---|---|---|
| Build works locally but fails in CI | Lockfile missing or out of date | Commit the lockfile and use npm ci |
| ERESOLVE peer dependency error | Incompatible peer version ranges | Align versions rather than forcing installs |
| Huge node_modules directory | Many transitive dependencies | Remove unused packages and review additions |
| Audit reports many warnings | Vulnerable transitive packages | Update parents or apply overrides |
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.