npm CLI

Common errors

• npm: command not found

  cause Node.js (and thus npm) is not installed, or the npm executable's directory is not included in the system's PATH environment variable.
  fix Install Node.js from the official website or via a Node Version Manager (nvm, fnm, volta). Verify Node.js and npm are installed by running `node -v` and `npm -v`. Check and update your system's PATH variable if necessary.

• npm ERR! code EACCES

  cause This error indicates a permissions issue when npm tries to write to system directories, typically during global package installations, because the current user lacks write permissions.
  fix The recommended fix is to use a Node Version Manager (like nvm) which manages Node.js and npm installations in user-writable directories. Alternatively, change npm's default global installation directory to a user-owned location, or fix existing directory permissions (use `sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}` with caution). Never use `sudo npm install -g` as a routine fix.

• npm ERR! code ERESOLVE
  npm ERR! ERESOLVE unable to resolve dependency tree

  cause npm's dependency resolution algorithm cannot find compatible versions for all packages simultaneously, often due to strict peer dependency rules introduced in npm 7+.
  fix Inspect the detailed error output to identify conflicting packages. Try `npm install --legacy-peer-deps` (for quick local fixes, not recommended for CI/production). Adjust versions in your `package.json` to satisfy requirements, or use the `overrides` field in `package.json` (npm 8+) to explicitly define transitive dependency versions.

Warnings

• breaking Node.js version compatibility is critical. `npm` versions are tightly coupled with Node.js LTS releases. For example, npm v11.x requires Node.js `^20.17.0 || >=22.9.0`. Using an incompatible Node.js version can lead to unexpected errors or installation failures.
  Fix: Always check the 'engines' field in `npm`'s package.json or the official documentation for compatible Node.js versions. Use a Node Version Manager (like nvm, fnm, or volta) to easily switch between Node.js versions.
• breaking Starting with npm 7, peer dependency resolution became stricter, treating previously acceptable conflicts as errors (ERESOLVE). This change ensures a more stable and predictable dependency tree but can break existing projects that relied on lenient peer dependency handling.
  Fix: Resolve dependency conflicts by aligning package versions. Use `npm install --legacy-peer-deps` as a temporary workaround (not recommended for production). For permanent fixes, consider `npm overrides` (npm 8+) to force specific transitive dependency versions.
• gotcha `package-lock.json` conflicts in source control are common. Manually editing `package-lock.json` is highly discouraged and can lead to inconsistent builds. Conflicts often arise from different `npm` or Node.js versions across development environments.
  Fix: After resolving `package.json` conflicts, run `npm install` (or `npm install --package-lock-only`) to automatically re-resolve `package-lock.json`. Consider using `npm ci` in CI/CD environments for reproducible builds that strictly adhere to the lockfile. Ensure all team members use consistent Node.js and npm versions.
• deprecated Direct programmatic usage of the main `npm` package (e.g., `require('npm')` or `import { run } from 'npm'`) is deprecated and often results in errors in newer npm versions. The internal API is not stable and does not follow semantic versioning.
  Fix: Prefer using `child_process.spawn` or `exec` to run npm commands as a CLI. For specific programmatic needs, use the dedicated `libnpm*` packages (e.g., `libnpminstall`, `libnpmpublish`, `@npmcli/arborist`) which provide stable, modular APIs for npm's underlying functionalities.

Install

• npm install npm npm
• yarn add npm yarn
• pnpm add npm pnpm

Imports

• install
  wrong:

  import { install } from 'npm'

  correct:

  import { install } from 'libnpminstall'

  The 'npm' package itself is primarily a CLI tool and not designed for direct programmatic import of its core commands. For programmatic package installation, developers typically use the 'libnpminstall' library, which npm itself consumes.
• publish
  wrong:

  import { publish } from 'npm'

  correct:

  import { publish } from 'libnpmpublish'

  Similar to installation, programmatic publishing functionality is exposed via 'libnpmpublish', a dedicated library that the npm CLI wraps.
• Arborist
  wrong:

  import { Arborist } from 'npm'

  correct:

  import Arborist from '@npmcli/arborist'

  For advanced scenarios involving direct manipulation or inspection of the dependency tree and package-lock files, the underlying '@npmcli/arborist' library provides programmatic access.

Quickstart

This quickstart demonstrates basic 'npm' command-line usage for initializing a project, installing local and global dependencies, and running package.json scripts.

// 1. Initialize a new Node.js project (if you don't have one)
//    This creates a package.json file.
// In your terminal:
// npm init -y

// 2. Install a common development dependency, e.g., 'lodash'
// In your terminal:
// npm install lodash

// 3. Install a global utility, e.g., 'nodemon' (for development servers)
// In your terminal:
// npm install -g nodemon

// 4. Create a simple JavaScript file (e.g., index.js)
// console.log('Hello from npm-managed project!');
// const _ = require('lodash');
// console.log(_.camelCase('hello world'));

// 5. Add a 'start' script to your package.json:
/*
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "lodash": "^4.17.21"
  }
}
*/

// 6. Run your project scripts
// In your terminal:
// npm start
// npm run dev (if nodemon is installed globally or locally)