(This could be made into a top-level doc, or integrated into the README, it comes up enough. Please edit this post or comment below if you have improvement suggestions. If someone wants to turn this into a PR then you're welcome to.)

Wot?

npm ships with its own version of node-gyp. Older versions of npm have older versions of node-gyp. npm has caught up recently to node-gyp's release cycle but it's expected we'll get out of sync and there will be cases where you need an old npm but a newer node-gyp, or npm doesn't ship yet with a node-gyp that we've released and it has fixes you need.

Generally, npm's library files are installed inside your global "node_modules", where npm is installed (run npm prefix and add lib/node_modules, or just node_modules for Windows [I think, Windows person - please confirm and edit this]). There are some exceptions to this. Inside this global node_modules/ there will be an npm/ directory and inside this you'll find a node_modules/node-gyp/ directory. So it may look something like /usr/local/lib/node_modules/npm/node_modules/node-gyp/. This is the version of node-gyp that ships with npm.

When you install a new version of node-gyp with outside of npm, it'll go into your global node_modules, but not under the npm/node_modules. So that may look like /usr/local/lib/node_modules/node-gyp/. It'll have the node-gyp executable linked into your PATH so running node-gyp will use this version.

The catch is that npm won't use this version unless you tell it to, it'll keep on using the one you have installed. You need to instruct it to by setting the node_gyp config variable (which goes into your ~/.npmrc). You do this by running the npm config set command as below. Then npm will use the command in the path you supply whenever it needs to build a native addon.

Important: You also need to remember to unset this when you upgrade npm with a newer version of node-gyp, or you have to manually keep your globally installed node-gyp to date. See "Undo" below.

Linux and macOS

npm install --global node-gyp@latest
npm config set node_gyp $(npm prefix -g)/lib/node_modules/node-gyp/bin/node-gyp.js

sudo may be required for the first command if you get a permission error.

Windows

@joaocgreis' Windows instructions from #1753 (comment)

Windows Command Prompt

npm install --global node-gyp@latest
for /f "delims=" %P in ('npm prefix -g') do npm config set node_gyp "%P\node_modules\node-gyp\bin\node-gyp.js"

Powershell

npm install --global node-gyp@latest
npm prefix -g | % {npm config set node_gyp "$_\node_modules\node-gyp\bin\node-gyp.js"}

Undo

Beware if you don't unset the node_gyp config option, npm will continue to use the globally installed version of node-gyp rather than the one it ships with, which may end up being newer.

npm uninstall --global node-gyp
npm config delete node_gyp