This article only describes how pnpm's
node_modules are structured when
there are no packages with peer dependencies. For the more complex scenario of
dependencies with peers, see how peers are resolved.
node_modules layout uses symbolic links to create a nested structure of
Every file of every package inside
node_modules is a hard link to the
content-addressable store. Let's say you install
firstname.lastname@example.org that depends on
email@example.com. pnpm will hard link both packages to
node_modules like this:
These are the only "real" files in
node_modules. Once all the packages are
hard linked to
node_modules, symbolic links are created to build the nested
dependency graph structure.
As you might have noticed, both packages are hard linked into a subfolder inside
node_modules folder (
firstname.lastname@example.org/node_modules/foo). This is needed to:
- allow packages to import themselves.
fooshould be able to
import * as package from "foo/package.json".
- avoid circular symlinks. Dependencies of packages are placed in the same
folder in which the dependent packages are. For Node.js it doesn't make a
difference whether dependencies are inside the package's
node_modulesor in any other
node_modulesin the parent directories.
The next stage of installation is symlinking dependencies.
bar is going to be
symlinked to the
Next, direct dependencies are handled.
foo is going to be symlinked into the
node_modules folder because
foo is a dependency of the project:
This is a very simple example. However, the layout will maintain this structure regardless of the number of dependencies and the depth of the dependency graph.
email@example.com as a dependency of
foo. This is how the new
structure will look:
As you may see, even though the graph is deeper now (
foo > bar > qar), the
directory depth in the file system is still the same.
This layout might look weird at first glance, but it is completely compatible
with Node's module resolution algorithm! When resolving modules, Node ignores
symlinks, so when
bar is required from
Node does not use
firstname.lastname@example.org/node_modules/bar, but instead,
resolved to its real location (
email@example.com/node_modules/bar). As a consequence,
bar can also resolve its dependencies which are in
A great bonus of this layout is that only packages that are really in the
dependencies are accessible. With a flattened
node_modules structure, all
hoisted packages are accessible. To read more about why this is an advantage,
see "pnpm's strictness helps to avoid silly bugs"