{"id":14767,"library":"npm","title":"npm CLI","description":"npm (Node Package Manager) is the default package manager for Node.js, providing a command-line interface for installing, sharing, and managing project dependencies. It interacts with the vast npm public registry, which hosts millions of JavaScript packages. The current stable version is 11.12.1, with frequent releases that include bug fixes, performance improvements, and new features. Its key differentiators include its ubiquitous adoption as the standard for Node.js development, its comprehensive registry, and integrated tools for tasks like package auditing, publishing, and script execution. npm is an indispensable tool for nearly all JavaScript and TypeScript projects utilizing the Node.js runtime.","status":"active","version":"11.12.1","language":"javascript","source_language":"en","source_url":"https://github.com/npm/cli","tags":["javascript","install","modules","package manager","package.json"],"install":[{"cmd":"npm install npm","lang":"bash","label":"npm"},{"cmd":"yarn add npm","lang":"bash","label":"yarn"},{"cmd":"pnpm add npm","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core internal dependency responsible for managing the node_modules tree and package-lock.json operations. It's fundamental for dependency resolution and installation logic.","package":"@npmcli/arborist","optional":false},{"reason":"Internal dependency providing the core logic for the 'npm diff' command, used to compare package versions.","package":"libnpmdiff","optional":false},{"reason":"Internal dependency that encapsulates the functionality for 'npm exec' and 'npx' commands, executing binaries from packages.","package":"libnpmexec","optional":false},{"reason":"Internal dependency that implements the 'npm fund' command, helping users discover and support package maintainers.","package":"libnpmfund","optional":false},{"reason":"Internal dependency for the 'npm pack' command, used to create gzipped tarballs of packages.","package":"libnpmpack","optional":false}],"imports":[{"note":"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.","wrong":"import { install } from 'npm'","symbol":"install","correct":"import { install } from 'libnpminstall'"},{"note":"Similar to installation, programmatic publishing functionality is exposed via 'libnpmpublish', a dedicated library that the npm CLI wraps.","wrong":"import { publish } from 'npm'","symbol":"publish","correct":"import { publish } from 'libnpmpublish'"},{"note":"For advanced scenarios involving direct manipulation or inspection of the dependency tree and package-lock files, the underlying '@npmcli/arborist' library provides programmatic access.","wrong":"import { Arborist } from 'npm'","symbol":"Arborist","correct":"import Arborist from '@npmcli/arborist'"}],"quickstart":{"code":"// 1. Initialize a new Node.js project (if you don't have one)\n//    This creates a package.json file.\n// In your terminal:\n// npm init -y\n\n// 2. Install a common development dependency, e.g., 'lodash'\n// In your terminal:\n// npm install lodash\n\n// 3. Install a global utility, e.g., 'nodemon' (for development servers)\n// In your terminal:\n// npm install -g nodemon\n\n// 4. Create a simple JavaScript file (e.g., index.js)\n// console.log('Hello from npm-managed project!');\n// const _ = require('lodash');\n// console.log(_.camelCase('hello world'));\n\n// 5. Add a 'start' script to your package.json:\n/*\n{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"description\": \"\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"start\": \"node index.js\",\n    \"dev\": \"nodemon index.js\"\n  },\n  \"keywords\": [],\n  \"author\": \"\",\n  \"license\": \"ISC\",\n  \"dependencies\": {\n    \"lodash\": \"^4.17.21\"\n  }\n}\n*/\n\n// 6. Run your project scripts\n// In your terminal:\n// npm start\n// npm run dev (if nodemon is installed globally or locally)","lang":"javascript","description":"This quickstart demonstrates basic 'npm' command-line usage for initializing a project, installing local and global dependencies, and running package.json scripts."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=11.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=8.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"npm: command not found"},{"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.","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.","error":"npm ERR! code EACCES"},{"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.","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+.","error":"npm ERR! code ERESOLVE\nnpm ERR! ERESOLVE unable to resolve dependency tree"}],"ecosystem":"npm"}