Frequently Asked Questions
node_modules
folder use disk space if packages are stored in a global store?#
Why does my pnpm creates hard links from the global store to the project's node_modules
folders. Hard links point to the same place on the disk where the original files are. So, for example, if you have foo
in your project as a dependency and it occupies 1MB of space, then it will look like it occupies 1MB of space in the project's node_modules
folder and the same amount of space in the global store. However, that 1MB is the same space on the disk addressed from two different locations. So in total foo
occupies 1MB, not 2MB.
For more on this subject:
- Why do hard links seem to take the same space as the originals?
- A thread from the pnpm chat room
- An issue in the pnpm repo
#
Does it work on Windows?Short answer: Yes Long answer: Using symbolic linking on Windows is problematic to say the least, however, pnpm has a workaround. For Windows, we use junctions instead.
node_modules
approach is incompatible with Windows?#
But the nested Early versions of npm had issues because of nesting all node_modules
(see this issue. However, pnpm does not create deep folders, it stores all packages flatly and uses symbolic links to create the dependency tree structure.
#
What about circular symlinks?Although pnpm uses linking to put dependencies into node_modules
folders, circular symlinks are avoided because parent packages are placed into the same node_modules
folder in which their dependencies are. So foo
's dependencies are not in foo/node_modules
, but foo
is in node_modules
together with its own dependencies.
#
Why have hard links at all? Why not symlink directly to the global store?One package can have different sets of dependencies on one machine.
In project A [email protected]
can have a dependency resolved to [email protected]
, but in project B the same dependency of foo
might resolve to [email protected]
; so, pnpm hard links [email protected]
to every project where it is used, in order to create different sets of dependencies for it.
Direct symlinking to the global store would work with Node's --preserve-symlinks
flag, however, that approach comes with a plethora of its own issues, so we decided to stick with hard links. For more details about why this decision was made, see this issue.
#
Does pnpm work across multiple drives or filesystems?The package store should be on the same drive and filesystem as installations, otherwise packages will be copied, not linked. This is due to a limitation in how hard linking works, in that a file on one filesystem cannot address a location in another. See Issue #712 for more details.
pnpm functions differently in the 2 cases below:
#
Store path is specifiedIf the store path is specified via the store config, then copying occurs between the store and any projects that are on a different disk.
If you run pnpm install
on disk A
, then the pnpm store must be on disk A
. If the pnpm store is located on disk B
, then all required packages will be directly copied to the project location instead of being linked. This severely inhibits the storage and performance benefits of pnpm.
#
Store path is NOT specifiedIf the store path is not set, then multiple stores are created (one per drive or filesystem).
If installation is run on disk A
, the store will be created on A
.pnpm-store
under the filesystem root. If later the installation is run on disk B
, an independent store will be created on B
at .pnpm-store
. The projects would still maintain the benefits of pnpm, but each drive may have redundant packages.
pnpm store prune
do? Is it harmful?#
What does The command pnpm store prune
removes unreferenced packages.
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 [email protected]
is updated to [email protected]
. pnpm will keep [email protected]
in the store, as it does not automatically remove packages. If package [email protected]
is not used by any other project on the system, it becomes unreferenced. Running pnpm store prune
would remove [email protected]
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.
pnpm
stand for?#
What does pnpm
stands for performant npm
. Rico Sta. Cruz came up with the name.
pnpm
does not work with <YOUR-PROJECT-HERE>?#
In most cases it means that one of the dependencies require packages not declared in package.json
. It is a common mistake caused by flat node_modules
. If this happens, this is an error in the dependency and the dependency should be fixed. That might take time though, so pnpm supports workarounds to make the buggy packages work.
#
Solution 1In the following example, a dependency does not have the iterall
module in its own list of deps.
The easiest solution to resolve missing dependencies of the buggy packages is to add iterall
as a dependency to our project's package.json
.
You can do so, by installing it via pnpm add iterall
, and will be automatically added to your project's package.json
.
#
Solution 2One of the solutions is to use hooks for adding the missing dependencies to the package's package.json
.
An example was Webpack Dashboard which wasn't working with pnpm
. It has since been resolved such that it works with pnpm
now.
It used to throw an error:
The problem was that babel-traverse
was used in inspectpack
which was used by webpack-dashboard
, but babel-traverse
wasn't specified in inspectpack
's package.json
. It still worked with npm
and yarn
because they create flat node_modules
.
The solution was to create a .pnpmfile.cjs
with the following contents:
After creating a .pnpmfile.cjs
, delete pnpm-lock.yaml
only - there is no need to delete node_modules
, as pnpm hooks only effect module resolution. Then, rebuild the dependencies & it should be working.
#
Solution 3In case there are too many issues, you can use the shamefully-hoist
option. This creates a flat node_modules
structure similar to the one created by npm
or yarn
, which is not recommended as avoiding this structure is the primary purpose of pnpm's node_modules
approach.
To use it, try pnpm install --shamefully-hoist
.