Skip to content

Commit c8c0af7

Browse files
committed
fix: doc how to update node-gyp independently from npm
1 parent b6e1cc7 commit c8c0af7

File tree

1 file changed

+21
-43
lines changed

1 file changed

+21
-43
lines changed

docs/Updating-npm-bundled-node-gyp.md

Lines changed: 21 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -6,63 +6,41 @@ not running a [current version of node-gyp](https://github.com/nodejs/node-gyp/r
66
`npm` bundles its own, internal, copy of `node-gyp`. This internal copy is independent of any globally installed copy of node-gyp that
77
may have been installed via `npm install -g node-gyp`.
88

9-
This means that while `node-gyp` doesn't get installed into your `$PATH` by default, npm still keeps its own copy to invoke when you
10-
attempt to `npm install` a native add-on.
9+
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). 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.
1110

12-
Sometimes, you may need to update npm's internal node-gyp to a newer version than what is installed. A simple `npm install -g node-gyp`
13-
_won't_ do the trick since npm will still continue to use its internal copy over the global one.
11+
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.
1412

15-
So instead:
13+
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.
1614

17-
## Version of npm
15+
**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.
1816

19-
We need to start by knowing your version of `npm`:
20-
```bash
21-
npm --version
17+
## Linux and macOS
2218
```
23-
24-
## Linux, macOS, Solaris, etc.
25-
26-
Unix is easy. Just run the following command.
27-
28-
If your npm is version ___7___, do:
29-
```bash
30-
$ npm explore npm/node_modules/@npmcli/run-script -g -- npm_config_global=false npm install node-gyp@latest
31-
```
32-
33-
Else if your npm is version ___less than 7___, do:
34-
```bash
35-
$ npm explore npm/node_modules/npm-lifecycle -g -- npm install node-gyp@latest
19+
npm install --global node-gyp@latest
20+
npm config set node_gyp $(npm prefix -g)/lib/node_modules/node-gyp/bin/node-gyp.js
3621
```
3722

38-
If the command fails with a permissions error, please try `sudo` and then the command.
23+
`sudo` may be required for the first command if you get a permission error.
3924

4025
## Windows
26+
@joaocgreis' Windows instructions from [#1753 (comment)](https://github.comnodejs/node-gyp/issues/1753#issuecomment-501827267)
4127

42-
Windows is a bit trickier, since `npm` might be installed to the "Program Files" directory, which needs admin privileges in order to
43-
modify on current Windows. Therefore, run the following commands __inside a `cmd.exe` started with "Run as Administrator"__:
44-
45-
First we need to find the location of `node`. If you don't already know the location that `node.exe` got installed to, then run:
46-
```bash
47-
$ where node
28+
### Windows Command Prompt
4829
```
49-
50-
Now `cd` to the directory that `node.exe` is contained in e.g.:
51-
```bash
52-
$ cd "C:\Program Files\nodejs"
30+
npm install --global node-gyp@latest
31+
for /f "delims=" %P in ('npm prefix -g') do npm config set node_gyp"%P\node_modules\node-gyp\bin\node-gyp.js"
5332
```
5433

55-
If your npm version is ___7___, do:
56-
```bash
57-
cd node_modules\npm\node_modules\@npmcli\run-script
34+
### Powershell
5835
```
59-
60-
Else if your npm version is ___less than 7___, do:
61-
```bash
62-
cd node_modules\npm\node_modules\npm-lifecycle
36+
npm install --global node-gyp@latest
37+
npm prefix -g | % {npm config set node_gyp "$_\node_modules\node-gyp\bin\node-gypjs"}
6338
```
6439

65-
Finish by running:
66-
```bash
67-
$ npm install node-gyp@latest
40+
## Undo
41+
**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.
42+
43+
```
44+
npm config delete node_gyp
45+
npm uninstall --global node-gyp
6846
```

0 commit comments

Comments
 (0)