Guide · Open source

How to use node-gyp: build native Node.js addons step by step

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

node-gyp is a command-line tool, written in Node.js, that compiles native addons: modules written in C or C++ that Node.js can load. This guide is for developers who publish or install Node.js packages with native code, or who need to build an addon for a specific Node.js or Electron version. By the end you will know the prerequisites, how to install node-gyp, and how to run the configure, build and rebuild commands on an addon with a binding.gyp file.

node-gypnodejs/node-gyp · ★ 10.7k · MIT Install options & downloads

Quick start

1Install prerequisites. Install a supported Python, make and a C/C++ compiler toolchain, plus Node.js with npm. On Windows, use the Chocolatey command or install Visual C++ tools manually.
2Install node-gyp. Run npm install -g node-gyp to make the node-gyp command available.
3Go to the addon directory. Change into the root directory of the addon, the folder that holds binding.gyp.
4Configure. Run node-gyp configure to generate Makefile or vcxproj files in the build/ directory.
5Build. Run node-gyp build to compile the addon into a .node file under build/Release/ or build/Debug/.
6Load and test. Require the .node file from Node.js and run your tests.

What you need before you install node-gyp

node-gyp needs Python, make and a C/C++ compiler toolchain, plus Node.js with npm. The requirements differ slightly by operating system. Python must be a version supported by node-gyp; the README notes that Python 3.12 or newer requires node-gyp v10 or later.

Unix: a supported Python, make, and a C/C++ toolchain such as GCC
macOS: a supported Python plus Xcode Command Line Tools, which install clang, clang++ and make
Windows: Python and the Visual C++ build tools, either installed with Chocolatey or manually through Visual Studio

Install node-gyp with npm

Install node-gyp globally with npm. On Windows you can first install Python and the Visual C++ tools with Chocolatey using the package named in the README.

npm install -g node-gyp

choco install python visualstudio2026-workload-vctools -y

Choose the right Python if you have several

If several Python versions are installed, node-gyp checks settings in a fixed order. You can pass the --python option on the command line, set the npm_config_python environment variable (useful when node-gyp runs through npm), set the PYTHON environment variable, or set NODE_GYP_FORCE_PYTHON to force one executable. The last option means no other Python will be searched if the path is incompatible.

--python: pass the path to the executable on each command
npm_config_python: set it when node-gyp is called through npm
PYTHON: used if it points to a supported version
NODE_GYP_FORCE_PYTHON: forces one executable and stops searching if it is incompatible

node-gyp <command> --python /path/to/executable/python

Build an addon with configure, build and rebuild

Go to the root directory of your addon, which must contain a binding.gyp file. Run configure to generate build files for your platform: a Makefile on Unix or a vcxproj file on Windows, placed in the build/ directory. Then run build. The compiled .node file appears in build/Release/, or build/Debug/ if you used the debug flag. You can then require the .node file from Node.js and run your tests.

Use --debug or -d with configure, build or rebuild to create a Debug build
rebuild runs clean, configure and build in a row
Auto-detection fails for Visual C++ Build Tools 2015, so add --msvs_version=2015 to configure

cd my_node_addon
node-gyp configure
node-gyp build

Write a binding.gyp file

A binding.gyp file describes how to build your module, in a JSON-like format. It sits in the root of your package, next to package.json. The README shows a minimal file with one target named binding that compiles src/binding.cc.

{
  "targets": [
    {
      "target_name": "binding",
      "sources": [ "src/binding.cc" ]
    }
  ]
}

Build for Electron or another third-party runtime

Runtimes such as Electron can have build configurations that differ from the official Node.js distribution. For these, pass --dist-url or --nodedir to point node-gyp at that runtime's headers. When either flag is set, node-gyp uses the config.gypi file shipped with the headers instead of process.config from the running Node.js. Some old Electron versions shipped a malformed config.gypi, and then --force-process-config may help.

node-gyp configure --dist-url=<runtime headers URL>
node-gyp configure --nodedir=<path to headers>

What people use it for

Publishing a Node.js package that includes C or C++ code and needs one build command across Unix, macOS and Windows
Building an addon against the headers of a specific Node.js version
Building an addon for Electron or another third-party runtime by using --dist-url or --nodedir
Rebuilding a native module after switching Python or compiler settings using rebuild

Frequently asked questions

How do I install node-gyp?

Run npm install -g node-gyp. You also need Python, make and a C/C++ compiler toolchain, plus Node.js with npm. On Windows, the README suggests installing Python and Visual C++ tools with Chocolatey.

Is node-gyp free to use?

node-gyp is licensed under MIT, an open-source licence. Check the repository's license file for the full terms.

Why does node-gyp say Python is not found?

node-gyp needs a supported version of Python. If several are installed, set --python, npm_config_python, PYTHON or NODE_GYP_FORCE_PYTHON to the correct executable path. The README lists these options in order.

Do I need node-gyp for a JavaScript-only project?

No. node-gyp compiles native C or C++ addons, so projects that contain only JavaScript do not need it.

Can node-gyp build Node.js itself?

No. The README states that node-gyp is not used to build Node.js itself. It compiles native addons for Node.js.

What are alternatives to node-gyp?

Comparable projects named in our analysis include cmake-js, prebuildify, node-pre-gyp and node-addon-api. Each takes a different approach to building or packaging native addons, so compare them against your project's needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

node-gyp is the standard choice if you are publishing or installing Node.js packages with C or C++ code and want one build command across Unix, macOS and Windows. If your project is JavaScript only, or you cannot install a C/C++ toolchain and Python, you do not need it and should look elsewhere.

Install options & downloads