npm-prune

Remove all extraneous packages not listed in dependencies

$ npm prune

$ npm prune --production

$ npm prune --dry-run

$ npm prune --json

$ npm prune [package_name]

npm prune []

npm prune --production

npm prune --dry-run

[]
    Optional path to the project directory where
npm prune should be executed. Defaults to the current working directory.


--production
    Removes
devDependencies (packages listed in
devDependencies in
package.json) from the
node_modules directory, treating them as unnecessary. Only production dependencies will remain.


--dry-run
    Performs a simulated run, showing which packages would be pruned without actually modifying the
node_modules directory. Useful for previewing changes.


--json
    Outputs the list of pruned packages in JSON format to standard output. Useful for programmatic parsing.


--omit
    Prevents pruning of specific dependency types. For example,
--omit=dev will keep
devDependencies, effectively similar to not using
--production.

The
npm prune command cleans up your
node_modules directory by removing packages that are not listed as dependencies in your
package.json file, or are not required by your
package-lock.json (if present). Its primary purpose is to free up disk space and ensure that your project's dependencies are minimal and strictly adhere to what's defined in your project's manifest. This is especially useful in production environments or CI/CD pipelines where you want to deploy only essential runtime dependencies, excluding development-specific packages.

When executed,
npm prune compares the contents of your
node_modules directory against the dependencies defined in
package.json and
package-lock.json, identifying and deleting any packages that are extraneous. This can include manually installed packages, outdated versions that didn't get removed during an update, or
devDependencies when the
--production flag is used. It helps maintain a clean and consistent dependency tree, preventing potential issues arising from lingering, unmanaged packages.

npm prune only removes packages from
node_modules; it
does not modify your
package.json or
package-lock.json files. If you've manually removed a dependency from your
package.json, running
npm prune will remove its corresponding files, but it won't prevent it from being reinstalled if another package depends on it implicitly or if your
package-lock.json still lists it as a dependency for some reason. Always ensure your
package.json reflects your desired dependencies before pruning. It can also be a slow operation for very large
node_modules folders.

npm prune is frequently used in Continuous Integration/Continuous Deployment (CI/CD) pipelines after
npm install. The typical flow involves running
npm install to get all dependencies, then running
npm prune --production to remove development-only dependencies before building and deploying the application. This minimizes the size of the deployment artifact and potential attack surface in production.

It's important to note that
npm install often performs an implicit pruning operation when a
package-lock.json file is present. If the contents of
node_modules do not match the state described in
package-lock.json,
npm install will attempt to bring it into line, which can include removing extraneous packages. However,
npm prune provides a dedicated and explicit command for this cleanup task, offering more control with its specific options.

The
npm prune command has been a fundamental part of the
npm CLI since its early versions, addressing the common need to manage the often extensive
node_modules directory. Its evolution has been tied to the growing complexity of JavaScript project dependencies and the emphasis on lean deployment artifacts. Initially, its role was straightforward cleanup, but with the introduction of
package-lock.json and more sophisticated dependency resolution,
npm prune gained a more precise mechanism for identifying truly extraneous packages, ensuring consistency across environments.

npm install(1), npm uninstall(1), npm ls(1), npm outdated(1)