Why pnpm Uses Content-Addressable Storage

pnpm uses content-addressable storage as a centralized repository to store all package dependencies on a machine, drastically reducing disk space usage and speeding up installation times. Instead of downloading duplicate packages across multiple projects, pnpm stores each unique file exactly once in a global store and links it to projects using hard links. This approach ensures high installation efficiency, data integrity, and deterministic dependency resolution.

How Content-Addressable Storage Works

Content-addressable storage identifies and indexes files based on their content rather than their file name or path. When pnpm downloads a package, it computes a cryptographic hash of each file in the package. If a file with the identical hash already exists in the global store, pnpm skips writing it to disk.

When creating the node_modules directory in a project, pnpm does not copy the files. Instead, it creates hard links that point directly to the corresponding files inside the global content-addressable store.

Primary Purposes and Benefits

1. Significant Disk Space Savings

In traditional package managers like npm or Yarn classic, if ten different projects use the same version of a large dependency, that dependency is duplicated ten times on the disk. With pnpm’s content-addressable storage: * Files are stored only once on the system. * Multiple projects reference the same physical blocks on the storage drive via hard links. * If a new version of a package updates only a few files, only those modified files are downloaded and saved to the store, while unchanged files are reused.

2. Drastically Faster Installations

Because files are stored globally by their content hash: * Skipped Downloads: pnpm verifies if a file already exists in the local store and avoids re-downloading it from the remote registry. * Instant File Linking: Creating a hard link inside a file system is a nearly instantaneous metadata operation, making node_modules generation significantly faster than copying physical files.

3. File Integrity and Verification

Since storage keys are derived directly from the content hash of the files, the content-addressable store inherently guarantees integrity. If a file becomes corrupted or modified, its hash changes, allowing pnpm to detect the discrepancy immediately and restore the correct file.

4. Preventing Phantom Dependencies

pnpm combines content-addressable storage with a symlinked directory structure to maintain a strict, non-flat node_modules tree. This ensures projects can only access the dependencies explicitly declared in their package.json, eliminating the “phantom dependency” bugs commonly encountered with flattened dependency trees.