node-gyp Cache
Native addon builds with node-gyp keep a local cache of downloaded Node.js header tarballs, unpacked include files, installVersion metadata, and architecture-specific build support files so packages with C/C++ bindings can compile against the correct runtime. That cache grows as different Node versions are installed and rebuilt, and stale or partially extracted headers can leave local builds pointing at the wrong ABI or an incomplete toolchain. Kudu removes the cached node-gyp header directories and downloaded build artifacts only, leaving your projects, node_modules, npm settings, accounts, and passwords untouched.
Why clean node-gyp Cache?
- A partial or interrupted header download leaves missing include files, and npm install fails with node-gyp errors such as ENOENT, fatal error: node_version.h: No such file or directory, or gyp ERR! configure error
- Headers cached for the wrong Node.js version or ABI cause native modules to rebuild against an incompatible target, which shows up as install failures or runtime messages like Module version mismatch after upgrading Node
- Corrupted installVersion metadata makes node-gyp think a broken cache is valid, so every rebuild reuses bad headers and the same package repeatedly fails until the cache is removed
- Old header trees accumulate for every Node release you have used, and the symptom is unexpectedly high disk usage under .node-gyp or AppData even when current projects are small
- Switching between x64, arm64, and Electron or standard Node targets can leave mixed cached build inputs behind, leading to confusing compile errors about missing symbols, wrong config.gypi values, or unsupported runtime targets
- A clean cache forces node-gyp to fetch fresh headers on the next build, which often resolves repeated native addon install failures that persist across npm cache cleans because the problem is in node-gyp's own header store
Cache paths Kudu targets
Windows
%LocalAppData%/node-gyp/Cache |
macOS
~/.node-gyp |
Linux
~/.node-gyp |
Common questions about node-gyp Cache
Download Kudu and reclaim your disk space.
Available on Windows, macOS, and Linux. No account required, no feature gates, no telemetry without consent. All cleaning targets are open source and community-auditable.