https://pnpm.io/assets/js/30dc594d.38e177b8.js

1"use strict";(self.webpackChunk=self.webpackChunk||[]).push([["39092"],{67400(e,s,n){n.r(s),n.d(s,{metadata:()=>o,default:()=>h,frontMatter:()=>d,contentTitle:()=>r,toc:()=>a,assets:()=>l});var o=JSON.parse('{"id":"faq","title":"Frequently Asked Questions","description":"Why does my node_modules folder use disk space if packages are stored in a global store?","source":"@site/versioned_docs/version-10.x/faq.md","sourceDirName":".","slug":"/faq","permalink":"/10.x/faq","draft":false,"unlisted":false,"editUrl":"https://github.com/pnpm/pnpm.io/edit/main/versioned_docs/version-10.x/faq.md","tags":[],"version":"10.x","lastUpdatedBy":"Zoltan Kochan","lastUpdatedAt":1771892155000,"frontMatter":{"id":"faq","title":"Frequently Asked Questions"}}'),i=n(91987),t=n(67008);let d={id:"faq",title:"Frequently Asked Questions"},r,l={},a=[{value:"Why does my <code>node_modules</code> folder use disk space if packages are stored in a global store?",id:"why-does-my-node_modules-folder-use-disk-space-if-packages-are-stored-in-a-global-store",level:2},{value:"Does it work on Windows?",id:"does-it-work-on-windows",level:2},{value:"But the nested <code>node_modules</code> approach is incompatible with Windows?",id:"but-the-nested-node_modules-approach-is-incompatible-with-windows",level:2},{value:"What about circular symlinks?",id:"what-about-circular-symlinks",level:2},{value:"Why have hard links at all? Why not symlink directly to the global store?",id:"why-have-hard-links-at-all-why-not-symlink-directly-to-the-global-store",level:2},{value:"Does pnpm work across different subvolumes in one Btrfs partition?",id:"does-pnpm-work-across-different-subvolumes-in-one-btrfs-partition",level:2},{value:"Does pnpm work across multiple drives or filesystems?",id:"does-pnpm-work-across-multiple-drives-or-filesystems",level:2},{value:"Store path is specified",id:"store-path-is-specified",level:3},{value:"Store path is NOT specified",id:"store-path-is-not-specified",level:3},{value:"What does <code>pnpm</code> stand for?",id:"what-does-pnpm-stand-for",level:2},{value:"<code>pnpm</code> does not work with &lt;YOUR-PROJECT-HERE&gt;?",id:"pnpm-does-not-work-with-your-project-here",level:2},{value:"Solution 1",id:"solution-1",level:3},{value:"Solution 2",id:"solution-2",level:3},{value:"Solution 3",id:"solution-3",level:3}];function c(e){let s={a:"a",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(s.h2,{id:"why-does-my-node_modules-folder-use-disk-space-if-packages-are-stored-in-a-global-store",children:["Why does my ",(0,i.jsx)(s.code,{children:"node_modules"})," folder use disk space if packages are stored in a global store?"]}),"\n",(0,i.jsxs)(s.p,{children:["pnpm creates ",(0,i.jsx)(s.a,{href:"https://en.wikipedia.org/wiki/Hard_link",children:"hard links"})," from the global store to the project's ",(0,i.jsx)(s.code,{children:"node_modules"}),"\nfolders. Hard links point to the same place on the disk where the original\nfiles are. So, for example, if you have ",(0,i.jsx)(s.code,{children:"foo"})," in your project as a dependency\nand it occupies 1MB of space, then it will look like it occupies 1MB of space in\nthe project's ",(0,i.jsx)(s.code,{children:"node_modules"})," folder and the same amount of space in the global\nstore. However, that 1MB is ",(0,i.jsx)(s.em,{children:"the same space"})," on the disk addressed from two\ndifferent locations. So in total ",(0,i.jsx)(s.code,{children:"foo"})," occupies 1MB, not 2MB."]}),"\n",(0,i.jsx)(s.p,{children:"For more on this subject:"}),"\n",(0,i.jsxs)(s.ul,{children:["\n",(0,i.jsx)(s.li,{children:(0,i.jsx)(s.a,{href:"https://unix.stackexchange.com/questions/88423/why-do-hard-links-seem-to-take-the-same-space-as-the-originals",children:"Why do hard links seem to take the same space as the originals?"})}),"\n",(0,i.jsx)(s.li,{children:(0,i.jsx)(s.a,{href:"https://gist.github.com/zkochan/106cfef49f8476b753a9cbbf9c65aff1",children:"A thread from the pnpm chat room"})}),"\n",(0,i.jsx)(s.li,{children:(0,i.jsx)(s.a,{href:"https://github.com/pnpm/pnpm/issues/794",children:"An issue in the pnpm repo"})}),"\n"]}),"\n",(0,i.jsx)(s.h2,{id:"does-it-work-on-windows",children:"Does it work on Windows?"}),"\n",(0,i.jsxs)(s.p,{children:["Short answer: Yes.\nLong answer: Using symbolic linking on Windows is problematic to say the least,\nhowever, pnpm has a workaround. For Windows, we use ",(0,i.jsx)(s.a,{href:"https://docs.microsoft.com/en-us

1/windows/win32/fileio/hard-links-and-junctions",children:"junctions"})," instead."]}),"\n",(0,i.jsxs)(s.h2,{id:"but-the-nested-node_modules-approach-is-incompatible-with-windows",children:["But the nested ",(0,i.jsx)(s.code,{children:"node_modules"})," approach is incompatible with Windows?"]}),"\n",(0,i.jsxs)(s.p,{children:["Early versions of npm had issues because of nesting all ",(0,i.jsx)(s.code,{children:"node_modules"})," (see\n",(0,i.jsx)(s.a,{href:"https://github.com/nodejs/node-v0.x-archive/issues/6960",children:"this issue"}),"). However, pnpm does not create deep folders, it stores all packages\nflatly and uses symbolic links to create the dependency tree structure."]}),"\n",(0,i.jsx)(s.h2,{id:"what-about-circular-symlinks",children:"What about circular symlinks?"}),"\n",(0,i.jsxs)(s.p,{children:["Although pnpm uses linking to put dependencies into ",(0,i.jsx)(s.code,{children:"node_modules"})," folders,\ncircular symlinks are avoided because parent packages are placed into the same\n",(0,i.jsx)(s.code,{children:"node_modules"})," folder in which their dependencies are. So ",(0,i.jsx)(s.code,{children:"foo"}),"'s dependencies\nare not in ",(0,i.jsx)(s.code,{children:"foo/node_modules"}),", but ",(0,i.jsx)(s.code,{children:"foo"})," is in ",(0,i.jsx)(s.code,{children:"node_modules"})," together with its\nown dependencies."]}),"\n",(0,i.jsx)(s.h2,{id:"why-have-hard-links-at-all-why-not-symlink-directly-to-the-global-store",children:"Why have hard links at all? Why not symlink directly to the global store?"}),"\n",(0,i.jsx)(s.p,{children:"One package can have different sets of dependencies on one machine."}),"\n",(0,i.jsxs)(s.p,{children:["In project ",(0,i.jsx)(s.strong,{children:"A"})," ",(0,i.jsx)(s.code,{children:"[email protected]"})," can have a dependency resolved to ",(0,i.jsx)(s.code,{children:"[email protected]"}),", but\nin project ",(0,i.jsx)(s.strong,{children:"B"})," the same dependency of ",(0,i.jsx)(s.code,{children:"foo"})," might resolve to ",(0,i.jsx)(s.code,{children:"[email protected]"}),"; so,\npnpm hard links ",(0,i.jsx)(s.code,{children:"[email protected]"})," to every project where it is used, in order to\ncreate different sets of dependencies for it."]}),"\n",(0,i.jsxs)(s.p,{children:["Direct symlinking to the global store would work with Node's\n",(0,i.jsx)(s.code,{children:"--preserve-symlinks"})," flag, however, that approach comes with a plethora of its\nown issues, so we decided to stick with hard links. For more details about why\nthis decision was made, see ",(0,i.jsx)(s.a,{href:"https://github.com/nodejs/node-eps/issues/46",children:"this issue"}),"."]}),"\n",(0,i.jsx)(s.h2,{id:"does-pnpm-work-across-different-subvolumes-in-one-btrfs-partition",children:"Does pnpm work across different subvolumes in one Btrfs partition?"}),"\n",(0,i.jsx)(s.p,{children:"While Btrfs does not allow cross-device hardlinks between different subvolumes in a single partition, it does permit reflinks. As a result, pnpm utilizes reflinks to share data between these subvolumes."}),"\n",(0,i.jsx)(s.h2,{id:"does-pnpm-work-across-multiple-drives-or-filesystems",children:"Does pnpm work across multiple drives or filesystems?"}),"\n",(0,i.jsxs)(s.p,{children:["The package store should be on the same drive and filesystem as installations,\notherwise packages will be copied, not linked. This is due to a limitation in\nhow hard linking works, in that a file on one filesystem cannot address a\nlocation in another. See ",(0,i.jsx)(s.a,{href:"https://github.com/pnpm/pnpm/issues/712",children:"Issue #712"})," for more details."]}),"\n",(0,i.jsx)(s.p,{children:"pnpm functions differently in the 2 cases below:"}),"\n",(0,i.jsx)(s.h3,{id:"store-path-is-specified",children:"Store path is specified"}),"\n",(0,i.jsxs)(s.p,{children:["If the store path is specified via ",(0,i.jsx)(s.a,{href:"/10.x/configuring",children:"the store config"}),", then copying\noccurs between the store and any projects that are on a different disk."]}),"\n",(0,i.jsxs)(s.p,{children:["If you run ",(0,i.jsx)(s.code,{children:"pnpm install"})," on disk ",(0,i.jsx)(s.code,{children:"A"}),", then the pnpm store must be on disk ",(0,i.jsx)(s.code,{children:"A"}),".\nIf the pnpm store is located on disk ",(0,i.jsx)(s.code,{children:"B"}),", then all required packages will be\ndirectly copied to the project location instead of being linked. This severely\ninhibits the storage and performance benefits of pnpm."]}),"\n",(0,i.jsx)(s.h3,{id:"store-path-is-not-specified",children:"Store path is NOT specified"}),"\n",(0,i.jsx)(s.p,{children:"If the store path is not set, then multiple stores are created (one per drive or\nfilesystem)."}),"\n",(0,i.jsxs)(s.p,{children:["If installation is run on disk ",(0,i.jsx)(s.code,{children:"A"}),", the store will be created on ",(0,i.jsx)(s.code,{children:"A"}),"\n",(0,i.jsx)(s.code,{children:".pnpm-store"})," under the filesystem root.  If later the installation is run on\ndisk ",(0,i.jsx)(s.code,{children:"B"}),", an independent store will be created on ",(0,i.jsx)(s.code,{children:"B"})," at ",(0,i.jsx)(s.code,{children:".pnpm-store"}),". The\nprojects would still maintain the benefits of pnpm, but each drive may have\nredundant packages."]}),"\n",(0,i.jsxs)(s.h2,{id:"what-does-pnpm-stand-for",children:["What does ",(0,i.jsx)(s.code,{children:"pnpm"})," stand for?"]}),"\n",(0,i.jsxs)(s.p,{children:[(0,i.jsx)(s.code,{children:"pnpm"})," stands for ",(0,i.jsx)(s.code,{children:"performant npm"}),".\n",(0,i.jsx)(s.a,{href:"https://github.com/rstacruz/",children:"@rstacruz"})," came up with the name."]}),"\n",(0,i.jsxs)(s.h2,{id:"pnpm-does-not-work-with-your-project-here",children:[(0,i.jsx)(s.code,{children:"pnpm"})," does not work with <YOUR-PROJECT-HERE>?"]}),"\n",(0,i.jsxs)(s.p,{children:["In most cases it means that one of the dependencies require packages not\ndeclared in ",(0,i.jsx)(s.code,{children:"package.json"}),". It is a common mistake caused by flat\n",(0,i.jsx)(s.code,{children:"node_modules"}),". If this happens, this is an error in the dependency and the\ndependency should be fixed. That might take time though, so pnpm supports\nworkarounds to make the buggy packages work."]}),"\n",(0,i.jsx)(s.h3,{id:"solution-1",children:"Solution 1"}),"\n",(0,i.jsxs)(s.p,{children:["In case there are issues, you can use the ",(0,i.jsx)(s.a,{href:"settings#nodeLinker",children:(0,i.jsx)(s.code,{children:"nodeLinker: hoisted"})})," setting.\nThis creates a flat ",(0,i.jsx)(s.code,{children:"node_modules"})," structure similar to the one created by ",(0,i.jsx)(s.code,{children:"npm"}),"."]}),"\n",(0,i.jsx)(s.h3,{id:"solution-2",children:"Solution 2"}),"\n",(0,i.jsxs)(s.p,{children:["In the following example, a dependency does ",(0,i.jsx)(s.strong,{children:"not"})," have the ",(0,i.jsx)(s.code,{children:"iterall"})," module in\nits own list of deps."]}),"\n",(0,i.jsxs)(s.p,{children:["The easiest solution to resolve missing dependencies of the buggy packages is to\n",(0,i.jsxs)(s.strong,{children:["add ",(0,i.jsx)(s.code,{children:"iterall"})," as a dependency to our project's ",(0,i.jsx)(s.code,{children:"package.json"})]}),"."]}

1),"\n",(0,i.jsxs)(s.p,{children:["You can do so, by installing it via ",(0,i.jsx)(s.code,{children:"pnpm add iterall"}),", and will be\nautomatically added to your project's ",(0,i.jsx)(s.code,{children:"package.json"}),"."]}),"\n",(0,i.jsx)(s.pre,{children:(0,i.jsx)(s.code,{className:"language-json",children:'  "dependencies": {\n    ...\n    "iterall": "^1.2.2",\n    ...\n  }\n'})}),"\n",(0,i.jsx)(s.h3,{id:"solution-3",children:"Solution 3"}),"\n",(0,i.jsxs)(s.p,{children:["One of the solutions is to use ",(0,i.jsx)(s.a,{href:"/10.x/pnpmfile#hooks",children:"hooks"})," for adding the missing\ndependencies to the package's ",(0,i.jsx)(s.code,{children:"package.json"}),"."]}),"\n",(0,i.jsxs)(s.p,{children:["An example was ",(0,i.jsx)(s.a,{href:"https://github.com/pnpm/pnpm/issues/1043",children:"Webpack Dashboard"})," which wasn't working with ",(0,i.jsx)(s.code,{children:"pnpm"}),". It has\nsince been resolved such that it works with ",(0,i.jsx)(s.code,{children:"pnpm"})," now."]}),"\n",(0,i.jsx)(s.p,{children:"It used to throw an error:"}),"\n",(0,i.jsx)(s.pre,{children:(0,i.jsx)(s.code,{className:"language-console",children:"Error: Cannot find module 'babel-traverse'\n  at /node_modules/[email protected]/node_modules/inspectpack/lib/actions/parse\n"})}),"\n",(0,i.jsxs)(s.p,{children:["The problem was that ",(0,i.jsx)(s.code,{children:"babel-traverse"})," was used in ",(0,i.jsx)(s.code,{children:"inspectpack"})," which\nwas used by ",(0,i.jsx)(s.code,{children:"webpack-dashboard"}),", but ",(0,i.jsx)(s.code,{children:"babel-traverse"})," wasn't specified in\n",(0,i.jsx)(s.code,{children:"inspectpack"}),"'s ",(0,i.jsx)(s.code,{children:"package.json"}),". It still worked with ",(0,i.jsx)(s.code,{children:"npm"})," and ",(0,i.jsx)(s.code,{children:"yarn"})," because\nthey create flat ",(0,i.jsx)(s.code,{children:"node_modules"}),"."]}),"\n",(0,i.jsxs)(s.p,{children:["The solution was to create a ",(0,i.jsx)(s.code,{children:".pnpmfile.cjs"})," with the following contents:"]}),"\n",(0,i.jsx)(s.pre,{children:(0,i.jsx)(s.code,{className:"language-js",children:"module.exports = {\n  hooks: {\n    readPackage: (pkg) => {\n      if (pkg.name === \"inspectpack\") {\n        pkg.dependencies['babel-traverse'] = '^6.26.0';\n      }\n      return pkg;\n    }\n  }\n};\n"})}),"\n",(0,i.jsxs)(s.p,{children:["After creating a ",(0,i.jsx)(s.code,{children:".pnpmfile.cjs"}),", delete ",(0,i.jsx)(s.code,{children:"pnpm-lock.yaml"})," only - there is no need\nto delete ",(0,i.jsx)(s.code,{children:"node_modules"}),", as pnpm hooks only affect module resolution. Then,\nrebuild the dependencies & it should be working."]})]})}function h(e={}){let{wrapper:s}={...(0,t.R)(),...e.components};return s?(0,i.jsx)(s,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},67008(e,s,n){n.d(s,{R:()=>d,x:()=>r});var o=n(71763);let i={},t=o.createContext(i);function d(e){let s=o.useContext(t);return o.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function r(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:d(e.components),o.createElement(t.Provider,{value:s},e.children)}}}]);