← All commands
THE COMMAND REFERENCE

npm

Install JavaScript packages and run a project's scripts.

Last updated

Portable / common

Implementation-level reference; examples are not certified for every installed version.

Overview

npm is the package manager that comes with Node.js. It downloads the libraries that a project depends on into a node_modules folder, records them in package.json, and runs the scripts that the project defines, such as npm test. The examples here use only your own folder, and the commands that download packages are reviewed only.

Background

npm is an open-source command with documentation at docs.npmjs.com. It talks to a public registry for downloads. The tool tested here is the npm that comes with the long-term-support Node.js on the host.

Examples

Print the installed version; reviewed only, because the output changes with each release:

npm --version

Start a project: npm init -y writes a package.json with default answers, and node reads its version:

npm init -y > /dev/null 2>&1 && node -p "require('./package.json').version"

Add a script to the project and run it; --silent hides the lines npm adds:

npm init -y > /dev/null 2>&1 && npm pkg set scripts.hi="echo hi" > /dev/null 2>&1 && npm run hi --silent

Download a package into this project; this needs the network and is reviewed only:

npm install left-pad

List what is installed; reviewed only because it needs an install first:

npm ls --depth=0

Subcommands

npm install downloads the packages that the project needs. npm run NAME runs a script from package.json. npm init creates a package.json.

Common mistakes

Run npm in the folder that holds package.json, or it uses a different project or none. npm install writes to node_modules and package-lock.json; commit the lock file and do not commit node_modules. A package can run code when it is installed, so install only what you trust. A global install (-g) changes your whole system; prefer npx or a project install. Do not use sudo with npm: it leaves files that you cannot change.

Portability

The commands are the same on every system, and details change between npm versions. The examples that use the network are reviewed only: they were not run by the tests, and the ones that call a public service were checked by hand on 2026-11-10. The two examples that start a project were executed on the npm of the host; the version example is reviewed only. The Common examples were executed on npm (the version that comes with the Node.js on the host) (see the development guide for the exact check).

References

Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.