How pnpm Saves Disk Space Using Hard Links

pnpm is a fast, disk-efficient JavaScript package manager that dramatically reduces storage usage by sharing package files across multiple projects on the same machine. Unlike traditional package managers that duplicate dependencies in every local node_modules directory, pnpm maintains a single global content-addressable store on your hard drive and uses hard links alongside symbolic links (symlinks) to connect those files to individual projects. This article explains the underlying mechanics of content-addressable storage, hard linking, and how pnpm prevents redundant file duplication.

The Traditional Storage Problem in Node.js

Traditional package managers like npm and standard Yarn historically copy every dependency into a project’s local node_modules folder. If you have ten different projects on your computer that all depend on the exact same version of a large framework or utility library, that library is downloaded and stored on your disk ten separate times. Over time, this causes significant disk bloat and slower install times.

Content-Addressable Storage (CAS)

At the core of pnpm’s architecture is a centralized global store, known as a content-addressable store.

When pnpm downloads a dependency: 1. It hashes the content of each file within the package (typically using SHA-512). 2. It stores the file in a single, centralized directory on your disk (for example, ~/.local/share/pnpm/store on Linux/macOS) indexed by its hash. 3. If multiple packages contain identical files—or if different versions of a package share unmodified files—those files are stored only once in the global store.

Because the storage system is indexed by content rather than package name or version, identical files are never duplicated in the global cache.

How Hard Links Save Disk Space

Rather than copying files from the global store into your project’s local directory, pnpm creates hard links.

A hard link is a filesystem-level reference that points directly to the existing data blocks (inode) of a file on your storage drive.

• Zero Additional Space: A hard link does not duplicate file contents. It simply creates an additional path or directory entry pointing to the exact same physical space on the disk.
• Direct File Access: To the operating system and Node.js runtime, a hard-linked file behaves exactly like a regular file inside node_modules.
• Cross-Project Sharing: If ten projects use lodash@4.17.21, all ten projects have node_modules files that point back to the single set of files in the global store. Disk space is consumed only once.

The Role of Symlinks in Structuring node_modules

While hard links share individual files from the store, pnpm uses symbolic links (symlinks) to construct the structure of the node_modules folder.

1. The .pnpm Virtual Store: pnpm creates a hidden directory at node_modules/.pnpm. Inside this directory, all project dependencies are organized in a flat structure, with each file hard-linked to the global content-addressable store.
2. Project Root Symlinks: In your root node_modules, pnpm creates symlinks that point only to the direct dependencies declared in your package.json.
3. Dependency Isolation: Transitive dependencies (dependencies of your dependencies) are symlinked within .pnpm rather than exposed at the root level.

This combination of hard links and symlinks creates an isolated, non-flat dependency tree. It eliminates phantom dependencies (importing packages that are not listed in package.json) while keeping disk usage to an absolute minimum.

Summary of Benefits

By combining content-addressable storage with hard links and symlinks, pnpm provides:

• Massive Disk Savings: Every unique file version exists on disk exactly once per drive.
• Faster Installations: Installing already-cached dependencies avoids network requests and disk write operations, as pnpm only needs to generate hard links and symlinks.
• Strict Dependency Resolution: The symlink-based layout prevents accidental access to unlisted transitive dependencies without sacrificing compatibility.