A Comprehensive Guide to Fixing Node-Gyp Issues on Windows

Article summary

node-gyp is a tool that enables the compilation of native add-on modules for Node in multiple platforms. It has widespread use and is included as a dependency in many NPM packages.

On most systems, this isn’t an issue, and installing node-gyp with the rest of your packages works as expected. Unfortunately, this is not the case with Windows, as is evidenced by this thread from 2015. The Windows environment makes getting node-gyp to work a less-than-stellar developer experience, full of multiple pitfalls and many ways for things to go wrong.

This guide is meant to help solve the issues that can arise when installing a package that requires node-gyp.

1. Try running npm install with the --no-optional flag.

If you’re lucky, the dependency that requires node-gyp will be optional, and you can skip the entire process required to get it working. Try running npm install –no-optional to install only the required dependencies.

If you run this and still get the error, I have bad news: You’re in for a bit of a ride. As we begin our journey into getting node-gyp up and running, here’s an important note for all of the steps that follow. Make sure that you’re always working in an elevated terminal (with administrator privileges) and that you restart your console whenever a download is complete.

2. Try downloading the windows-build-tools package.

According to the node-gyp documentation, this step should be the end-all-be-all solution to fixing node-gyp problems. For most people, that’s true. NPM has a package called windows-build-tools that should automatically install everything you need to get node-gyp working, including the Microsoft build tools, compilers, Python, and everything else required to build native Node modules on Windows.

The good news is that installing this package should take care of all of the wiring up of these components. The bad news is that there are a lot of things included in it.

Depending on the version you download, it can hover between three and eight gigabytes (all to get some dependencies installed!). The install can take upwards of 30 minutes depending on your connection, so don’t despair if it seems like the install is hanging for a while.

You can download them by running this command: npm install --global --production windows-build-tools --vs2015

Important note

If you run this command without any additional flags, you’ll install the files associated with the latest version of Visual Studio, which is VS2017 at the time of writing. However, node-gyp requires the v140 distributable, not the v150 (which comes with VS2017). This is why the --vs2015 flag is added to the end of the command, since that’s the last version of Visual Studio that came with the v140 package. You can see more notes about that near the bottom of the package’s website.

Hopefully, that’s all it will take for you to get everything installed. If you’ve still got issues, then you’re going to have to grab all of the required files manually.

3. Download the Visual Studio 2015 build tools manually.

Rather than installing the build tools through NPM, download them manually. You can find them on the Microsoft download page. Once they’re downloaded, just run the installer.

4. Tell Node to use the 2015 build tools.

Now that we have the build tools, we need to tell Node to use them. You’ll have to run this command: npm config set msvs_version 2015 –global

5. Make sure you have Python 2.7 installed.

Next up is to download Python 2.7. This is important–by default, you’ll install the newest version (3.x.x), but only 2.7 is compatible with node-gyp. If you try to use a newer version of Python, you’ll get a syntax error due to print being made into an actual function in Python 3.

If you have another version of Python already installed, that’s okay. They can coexist with each other. You can grab Python 2.7 at this link.

6. Set your Node config to use Python 2.7.

Now that you have Python 2.7, you’re going to have to set Node to use it by default. To do that, run this command: npm config set python python2.7

If you followed the last few steps, you should now have everything necessary to get node-gyp working. Make sure you’ve restarted your terminal and are running it as an administrator, and try doing your install again. Hopefully, at this point, you can successfully install the dependencies you need. If not, we’re going to have to try one last thing.

7. Repeat Step 2 with the Visual Studio 2017 build tools.

I’ve personally had issues when I’ve tried to download the 2017 version of the build tools, even when trying to use newer versions of node-gyp. If you look online, you’ll see lots of other people with the same problem, including some of the commenters on this StackOverflow question.

However, most of the documentation around node-gyp and compiling native Node modules on Windows doesn’t specify to use the --vs2015 flag, and some even mention downloading the 2017 version. If you’re still having issues with getting node-gyp to run, try repeating Step 2 while omitting the --vs2015 flag.

8. Try installing an older version of Node.

Still getting an installation error? Try installing an older version of Node. If you’re on an experimental version, try going back to the last stable release (and then make sure that you’re actually using that version when you try and do npm install).

If that still doesn’t work, try going back to Node 8. You’ll find some issues online of people having issues with Node 10 that were resolved by downgrading to Node 8, and sometimes newer versions of Node don’t play nice with node-gyp.

9. File an issue.

If you’re still having trouble getting node-gyp to work, then your issue probably doesn’t fall into one of the more common problems. It’s worth doing some research online to see if that solves your problem. Otherwise, your best option is to file an issue on the GitHub page for node-gyp and see what advice you can get there.

Other Resources

Much of this information can now be found on the GitHub readme for node-gyp, but it wasn’t always there. It only made an appearance after a few thousand posts from disgruntled Windows users who just wanted to install some dependencies. Even then, the information is missing some of the issues that arise with installing the wrong version of the build tools.

Another great resource is Microsoft’s guide on working with Node on Windows. It even has sections dedicated to compiling native Node modules and resolving basic node-gyp problems.

Additionally, this question on StackOverflow contains useful answers and comments regarding this issue. Leave a note in the comments if you’ve found anything else helpful in solving node-gyp issues!

  • Shahriar says:

    Your tips were very useful; Especially the “–vs2015” part. Thanks!

  • Malcolm Swaine says:

    Good post, thanks brutha!

  • Andreas Markussen says:

    I on a nodejs-lts 10.16.3, I had to do this to make it work

    npm config set python python2

    Here is my setup:

    + [email protected]
    node -v => v10.16.3
    npm -v => 6.9.0
    cmd -v => Microsoft Windows [Version 10.0.17763.55]

    Thanks for the article

    • Joe Bustamante Joe Bustamante says:

      Hey Andreas, thanks for posting that. Did doing step #6 (using python2.7 instead of python2) not work initially? Glad it was helpful!

  • Matthew Dykeman says:

    Hey Joe,

    I just wanted to say thank you very much for writing this blog entry. I would have had to do a lot of deep dives into stackoverflow if you hadn’t written this. Following your guide I was able to get node-gyp to yell at my PowerShell less (It still spits out a good amount of warnings here and there ;)). But I am able to develop with React and that’s all I care about at the moment.

    Thanks Again!

    • Joe Bustamante Joe Bustamante says:

      Ha, good to hear Matthew – it’s hard to make node-gyp totally happy. Glad it was helpful though and you’re able to move forward!

  • Amit Shokeen says:

    I’m a newbie at Electron and your article proved very useful. Thanks!
    I share steps below to explain my issue and a solution:

    1. My problems started when I installed a node module named bcrypt.

    2. > electron-rebuild bcrypt
    did not help, so I went through the steps in your article.

    3. Following the steps you have suggested, the electron-rebuild step worked, but…

    4. > npm start
    this command still gave me an unhandled Javascript error which basically stated “…This version of Node.js requires NODE_MODULE_VERSION 70….”

    5. I tried a lot without success and was about to give up when I ran this command:
    > electron .
    That got my program to run successfully. So the problem now lies with npm & I still haven’t got my head around that yet.
    Hope this helps others looking to get out of a similar mess.

    • Joe Bustamante Joe Bustamante says:

      Hey Amit, thanks for sharing what worked for you. Glad the article was helpful!

  • Howard Bates says:

    You are a HERO! I want to PayPal you some $$. Seriously. I worked for hours trying to get sqlite3 installed after upgrading to node 13.0.1.

    • Joe Bustamante Joe Bustamante says:

      Ha, thanks Howard, no payment necessary! Glad this was helpful to you.

  • Ford Crosby says:

    Bro –

    Thank you SO much for consolidating this knowledge and making it understandable. I was a few clicks away from just cutting-bait when I found this article. Youdaman!

    • Joe Bustamante Joe Bustamante says:

      Hey Ford, no problem, glad to hear that this was helpful for you!

  • Adham says:

    You saved my day,
    step 3 (Download the Visual Studio 2015 build tools manually.) was very important for me , because installing through NPM makes my PC stuck in installing , infinity installing process.
    In step 7, I repeated step 2 with flag 2015.
    Then it works. npm i bcrypt, doen successfully .
    *In december last year, I did not have that problem. everything was compatible .

    • Joe Bustamante Joe Bustamante says:

      Hey Adham, I’m glad to hear that was helpful. Thanks for posting that for others who might have the same issue.

  • OMG! I can not thank you enough. It requires python 2.7- I simply downloaded it and set its config path using “npm config set python python2.7” to run everything and that was the only thing I was missing. You saved me from downloading the entire build tools again and a ton of time. Thanks bud :)

  • Vignesh says:

    Thanks a lot Joe!

    I spent two days trying to get the latest Electron and SQLite work together without any success. Using different versions (node, electron, SQLite3), different modules (every module except SQL.js) and kept on hitting one roadblock or other. Finally it is at:
    • rebuilding native dependencies [email protected] platform=win32 arch=x64

    A couple of points:
    * Due to frustration, I uninstalled and re-installed Node.js – bad move, since the env path variable was gone and had to be added manually.
    * ‘npm config set python python2.7’ -> led to ‘python2.7′ is not recognized as an internal or external command…’. It was fixed after adding ‘npm config set python python’.
    * I could not get gyp to recognize msvs_version 2015 – I do not have v140/150 installed (at least where npm was looking for it), but have VS 2017 and 2019, so used ‘msvs_version 2017’ instead.

    Thanks again! BTW, the installation completed by the time I typed this.


  • Derek says:

    There’s a typo,
    npm config set msvs_version 2015 –global
    should be
    npm config set msvs_version 2015 –global

    Two dashes, not an em mark

  • Shubhang Sharma says:

    Thanks for the tips. Helped me a lot. Was stuck for hours.
    My knight in shining armour :P

  • Ankush Upadhyay says:

    Thank you so much man.
    you don’t even know how much happy i am right now ^_^

  • phani kiran says:

    Thanks for those detailed steps. It worked !

  • rabdu admarh says:

    Normally I don’t comment anythin but THANK YOU all my day on this and finally im able to start working on the project!

  • Priya Varghese says:

    Thank You, after looking around for a really long time luckily landed on your page.
    This page had the solution.. Running “npm install -no-optional” fixed the issue for me.
    I have posted this link in stackoverflow as well.
    Thank You again.

  • Comments are closed.