pnpm store

Managing the package store.

Commands#

status#

Checks for modified packages in the store.

Returns exit code 0 if the content of the package is the same as it was at the time of unpacking.

add#

Functionally equivalent to pnpm add, except this adds new packages to the store directly without modifying any projects or files outside of the store.

prune#

Removes unreferenced packages from the store.

Unreferenced packages are packages that are not used by any projects on the system. Packages can become unreferenced after most installation operations, for instance when dependencies are made redundant.

For example, during pnpm install, package foo@1.0.0 is updated to foo@1.0.1. pnpm will keep foo@1.0.0 in the store, as it does not automatically remove packages. If package foo@1.0.0 is not used by any other project on the system, it becomes unreferenced. Running pnpm store prune would remove foo@1.0.0 from the store.

Running pnpm store prune is not harmful and has no side effects on your projects. If future installations require removed packages, pnpm will download them again.

It is best practice to run pnpm store prune occasionally to clean up the store, but not too frequently. Sometimes, unreferenced packages become required again. This could occur when switching branches and installing older dependencies, in which case pnpm would need to re-download all removed packages, briefly slowing down the installation process.

After pruning, pnpm displays the total size of removed files.

If pnpm cannot decode a package index entry, it keeps the entry and reports the number of undecodable entries in the summary. Pruning continues for other entries. Keeping an index entry does not preserve its unreferenced files. A later install downloads the package again if it cannot reuse the stored files.

Since v12.7.0, pnpm store prune also removes private copies of pnpm or a runtime that a killed pnpm process left behind. pnpm makes such a copy when a project pins a version that another pnpm process is installing at that moment.

pnpm install registers the project in {storeDir}/v11/projects/, with or without the global virtual store. Each entry is a symlink to the project directory, so ls -l "$(pnpm store path)/projects" lists the projects that use a store. Without the global virtual store, an install with --frozen-store or enableModulesDir: false does not write the registry. Neither do --lockfile-only and --dry-run installs.

When the global virtual store is enabled, pnpm store prune also performs mark-and-sweep garbage collection on the global virtual store's links/ directory. It walks the registered projects to find the packages still in use and removes the rest. If no registered project links into links/, prune leaves it unchanged.

path#

Returns the path to the active store directory.