pnpm store

Managing the package store.

Commands#

status#

Checks the packages listed in the current project's lockfile for modifications in the project or global virtual store.

Returns exit code 0 if the content of the package is the same as it was at the time of unpacking. Otherwise it fails with ERR_PNPM_MODIFIED_DEPENDENCY and lists the modified packages.

If an installed global-store package cannot be located or its project link points to a different slot, the command fails with ERR_PNPM_STORE_STATUS_UNVERIFIABLE. Run pnpm install before checking again.

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.

pnpm store add express@4

It also takes package tarballs or directories of tarballs that were downloaded some other way, searching directories recursively for .tgz, .tar.gz, and .tar archives. This prepares the store for an install without network access, such as a sandboxed build that downloads its sources ahead of time:

pnpm store add ./tarballs
pnpm install --offline --frozen-lockfile

An install takes a registry package from such a tarball when its lockfile entry names the same package and version and pins that tarball. The entry's integrity can be the tarball's sha512 or sha1, or the hash of the uncompressed tar inside it, which lockfile.integrityTarget: tar records.

For a package from a named registry that the project declares, run pnpm store add in that project.

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.

Before pruning the store, pnpm deletes the expired entries of the pnx cache (see dlxCacheMaxAge), because they hold hard links into the store.

pnpm store prune also removes the package metadata cache: the metadata* directories in the cache directory and in its versioned subdirectories, such as v12/metadata. Other caches in the cache directory are kept. The next install downloads the metadata again.

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 the projects directory of the store, "$(pnpm store path)/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.

pnpm store prune removes the directory-clone cache used by local installs on macOS. Installed packages remain available, and later installs recreate the cache as needed. The cache requires the store and project to be on the same volume. A frozen store uses per-file imports when its cache is missing.

When the global virtual store is enabled, pnpm store prune also performs mark-and-sweep garbage collection on its 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.

Pruning stops if a dependency link cannot be read.

path#

Returns the path to the active store directory.