gyp ERR!の原因と直し方｜npm installのnode-gyp失敗

この記事で実際に動かしたもの：自作の小さなネイティブモジュール（C++ 十数行）と、bcrypt・better-sqlite3・libpq の実物を、Python・make・g++ を PATH から外した環境で npm install し、gyp ERR! のログの原文と、直したあとの出力・時間を記録しました。

flowchart TD
    E[gyp ERR! が出た] --> P[find Python なら<br>Python を入れる・指定]
    P -->|違う| M[not found・No such file なら<br>make・g++ を入れる]
    M -->|違う| H[network・403 なら<br>nodedir でヘッダー]
    H -->|違う| V[prebuilt 404 なら<br>モジュールか Node の版]
    V -->|違う| L[ヘッダーが無いなら<br>-dev パッケージ]

知りたいことごとに、いちばん早い方法を先にまとめます。

確認環境：Ubuntu 24.04.5 LTS（Linux カーネル 6.18、x64、2 CPU）の上で、Node.js 22.23.4（npm 10.9.9 に同梱の node-gyp 11.5.0）、比べるために Node.js 20.20.0（npm 10.8.2・node-gyp 10.1.0）を使いました。ビルドツールは GCC 13.3.0・GNU Make 4.3・Python 3.13.18 です。ホストの python・make・g++ は消さず、必要なコマンドだけをリンクしたフォルダーを作って env -i PATH=そのフォルダー で npm を動かし、Python だけ・make だけ・g++ だけ・アセンブラ（as）だけが無い状態を作りました。npm のキャッシュと node-gyp のヘッダー置き場（devdir）は作業用のメモリ上のフォルダーに向け、ホームと共有の場所には何も置いていません。パッケージは npm レジストリと GitHub のリリースから読み取りだけで取得し、Node.js のヘッダー配布元（nodejs.org）への接続はこの環境では断られたため、その失敗自体をエラーの例として載せています。libpq のヘッダーは apt-get download した .deb を作業用のフォルダーに展開して使い、apt install はしていません。出力に出るパスは、読みやすさのため作業用のフォルダーを /work に置き換えています。Windows・Mac の手順は手元で動かせないため、node-gyp の公式 README、npm Docs、Node.js 公式ドキュメント（Node-API）、Microsoft Learn で確かめた範囲だけを書いています。図は mermaid で描画を確かめています（確認日 2026年11月6日）。

gyp ERR!とは（npm installのログの読み方）

この節では、gyp ERR! が何を意味し、長いログのどこを見れば原因に近づけるのかが分かります。

gyp ERR! は、node-gyp（Node.js のネイティブアドオンをビルドする公式のツール）が出すエラーの印です。npm Docs の scripts のページには、パッケージの直下に binding.gyp があり、install のスクリプトが書かれていなければ、npm は install の処理を node-gyp rebuild でのビルドにする、と書かれています。つまり gyp ERR! は「JavaScript だけでは動かないパッケージを、手元のパソコンの上でコンパイルしようとして失敗した」という合図で、npm そのものの不具合ではありません。

Python を外した環境で、自作の小さなネイティブモジュールを入れたときの原文です（npm 10 では、行の先頭が npm error になります）。

$ npm install ../hello-addon-1.0.0.tgz
npm error code 1
npm error path /work/app/node_modules/hello-addon
npm error command failed
npm error command sh -c node-gyp rebuild
npm error gyp info it worked if it ends with ok
npm error gyp info using node-gyp@11.5.0
npm error gyp info using node@22.23.4 | linux | x64
npm error gyp ERR! find Python
npm error gyp ERR! find Python Python is not set from command line or npm configuration
npm error gyp ERR! find Python Python is not set from environment variable PYTHON
npm error gyp ERR! find Python checking if "python3" can be used
npm error gyp ERR! find Python - executable path is ""
...
npm error gyp ERR! configure error
npm error gyp ERR! stack Error: Could not find any Python installation to use
npm error gyp ERR! stack at PythonFinder.fail (.../node-gyp/lib/find-python.js:306:11)
npm error gyp ERR! System Linux 6.18.44-fc-v242
npm error gyp ERR! command "/opt/node22/bin/node" ".../node-gyp/bin/node-gyp.js" "rebuild"
npm error gyp ERR! cwd /work/app/node_modules/hello-addon
npm error gyp ERR! node -v v22.23.4
npm error gyp ERR! node-gyp -v v11.5.0
npm error gyp ERR! not ok
npm error A complete log of this run can be found in: /work/.npm/_logs/2026-11-06T04_19_10_127Z-debug-0.log

見る場所は4つです。

npm 6 では、同じ失敗が npm ERR! code ELIFECYCLE と Failed at the hello-addon@1.0.0 install script. で終わります。前の版の npm を使うプロジェクトや、ネットで見つかる記事のログがこの形でも、中身の gyp ERR! の読み方は同じです。手元で npm 6.14.18 を一時的に動かしたときの末尾です。

gyp ERR! configure error
gyp ERR! stack Error: Could not find any Python installation to use
...
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! hello-addon@1.0.0 install: `node-gyp rebuild`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the hello-addon@1.0.0 install script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

自分で確かめる（ターミナルで1行）：ログが長くて流れてしまったら、最後の行に出るログファイルを grep -n "gyp ERR! stack Error\|error:" ログファイルのパス で絞ると、原因の行だけが残ります。npm 10 は成功したビルドの出力を表示しないため、途中経過を見たいときは npm install --foreground-scripts を付けます（npm Docs の scripts のページに、npm 7 以降はスクリプトの出力が表示されないこと、見るにはこの指定を使うことが書かれています）。

gyp ERR!・node-gyp rebuild failedの原因一覧

この節では、gyp ERR! の主な原因と、ログに出る目印、直し方を1枚で見渡せます。

原因は「道具が無い」「材料（ヘッダー）が取れない」「ソースと Node の版が合わない」の3つに分かれます。手元で実際に起こしたものは「再現」、公式ドキュメントで確かめたものは「公式」と書いています。

ネイティブモジュールのインストールは、次の順番で進みます。どこで止まったかを、ログの目印と照らし合わせます。

1. 1prebuilt を探す（prebuild-install・node-pre-gyp・node-gyp-build）見つかればここで終わり。Python もコンパイラも使わない
2. 2node-gyp configure：Python を探し、Node.js のヘッダーを用意するfind Python・gyp http の行が出る段階
3. 3node-gyp build：make が g++ を呼んでコンパイルするCXX(target) の行のあとに error: が出る段階
4. 4できた .node ファイルを require で読み込むNODE_MODULE_VERSION の不一致はここで出る

gyp ERR! find Python（Pythonが見つからない）

この節では、Python が無いときの原文と、入れる・場所を指定するの2つの直し方が分かります。

node-gyp は、ビルドの設定ファイル（Makefile）を作るのに Python を使います。node-gyp の README は、Python の探し方を次の順番と説明しています。

1. --python の指定（node-gyp rebuild --python /path/to/python）
2. npm の設定 npm_config_python（npm 経由で動くとき）
3. 環境変数 PYTHON
4. どれも無ければ PATH の python3、次に python

先ほどの原文で checking if "python3" can be used → executable path is "" となっているのは、4番目の PATH の検索で見つからなかったという意味です。Python は入っているのに PATH に無い場合は、場所を教えるだけで直ります。

$ npm_config_python=/usr/local/bin/python3 npm install --foreground-scripts ../hello-addon-1.0.0.tgz
gyp info find Python using Python version 3.13.18 found at "/usr/local/bin/python3"
...
gyp info ok
added 1 package in 576ms

$ PYTHON=/usr/bin/python3.12 npm install --foreground-scripts ../hello-addon-1.0.0.tgz
gyp info find Python using Python version 3.12.3 found at "/usr/bin/python3.12"
...
gyp info ok
added 1 package in 686ms

Python そのものが無ければ入れます。OS ごとの入れ方は次のとおりです（Windows・Mac は node-gyp の README の範囲）。

• Ubuntu・Debian：sudo apt install python3（多くの場合は最初から入っています）
• Mac：README は「サポートされている版の Python」を求めています。Homebrew などで入れた python3 を PATH に置きます
• Windows：README は Chocolatey での一括インストール（python と Visual Studio の C++ ツール）か、Python の公式インストーラーを案内しています

Python の版が合わないときの症状と、node-gyp の版との組み合わせは「node-gyp が前の版」の節で扱います。pip のビルドでも同じ「コンパイラが無い」問題が起き、別記事「subprocess-exited-with-errorの原因9つと直し方｜pip」（公開準備中）でまとめています。

not found: make・g++: No such file or directory（ビルドツールが無い）

この節では、make・C++ コンパイラ・アセンブラが無いときに、それぞれどんな原文になるかと、入れるものが分かります。

Python があっても、make と C++ コンパイラ（Linux は g++、Mac は clang++）が無ければビルドできません。1つずつ外して起こした原文です。

make が無い

npm error gyp info find Python using Python version 3.13.18 found at "/work/bin/python3"
npm error gyp info spawn /work/bin/python3
npm error gyp ERR! build error
npm error gyp ERR! stack Error: not found: make
npm error gyp ERR! stack at getNotFoundError (.../npm/node_modules/which/lib/index.js:16:17)
npm error gyp ERR! stack at which (.../npm/node_modules/which/lib/index.js:77:9)
npm error gyp ERR! stack at async doWhich (.../node-gyp/lib/build.js:120:22)
npm error gyp ERR! not ok

g++ が無い

make は動きますが、make が呼ぶ g++ が見つからず、終了コード 127（コマンドが無い）で止まります。gyp ERR! の行は `make` failed with exit code: 2 としか言わないため、その上の make: の行が本当の原因です。

npm error make: Entering directory '/work/app/node_modules/hello-addon/build'
npm error   CXX(target) Release/obj.target/hello/hello.o
npm error make: g++: No such file or directory
npm error make: *** [hello.target.mk:108: Release/obj.target/hello/hello.o] Error 127
npm error gyp ERR! build error
npm error gyp ERR! stack Error: `make` failed with exit code: 2

C のソースを含むパッケージ（better-sqlite3 の sqlite3.c など）では、g++ ではなく make: cc: No such file or directory になります。

アセンブラ（as）が無い

g++ だけを入れて binutils が欠けていると、次の形になります。最小構成の Docker イメージで起きやすい原文です。

npm error g++: fatal error: cannot execute 'as': execvp: No such file or directory
npm error compilation terminated.
npm error make: *** [hello.target.mk:108: Release/obj.target/hello/hello.o] Error 1
npm error gyp ERR! build error

Ubuntu・Debian では、make・g++・binutils をまとめて入れる build-essential を入れると、3つとも直ります。道具をそろえて同じパッケージを入れ直した結果です。

$ sudo apt install -y build-essential python3   # 手元では既に入っているものを PATH に戻して確認
$ npm install --foreground-scripts ../hello-addon-1.0.0.tgz
> hello-addon@1.0.0 install
> node-gyp rebuild

gyp info using node-gyp@11.5.0
gyp info find Python using Python version 3.13.18 found at "/work/bin/python3"
gyp info spawn make
make: Entering directory '/work/app/node_modules/hello-addon/build'
  CXX(target) Release/obj.target/hello/hello.o
  SOLINK_MODULE(target) Release/obj.target/hello.node
  COPY Release/hello.node
make: Leaving directory '/work/app/node_modules/hello-addon/build'
gyp info ok
added 1 package in 620ms

$ node -e "console.log(require('hello-addon').hello())"
hello from C++

自分で確かめる（ターミナルで1行）：which python3 make g++ as を実行し、表示されないものがあれば、それが足りない道具です。Mac では xcode-select --install で Command Line Tools（clang・clang++・make）を入れる、と node-gyp の README に書かれています。

node-gypのヘッダーの取得に失敗する（ENOTFOUND・403・プロキシ）

この節では、Node.js のヘッダーをダウンロードできないときの原文と、プロキシの設定・ローカルのヘッダーを使う方法が分かります。

node-gyp は、ビルドの前に、使っている Node.js と同じ版のヘッダー（node.h など）を nodejs.org から取得し、devdir（ヘッダー置き場）に保存します。devdir の場所は node-gyp の README で「OS のキャッシュのフォルダー」とされ、node-gyp のソースでは env-paths で決めています。手元で OS ごとの値を出すと次のとおりでした。

会社のネットワークなどで nodejs.org に届かないと、configure の段階で止まります。名前が引けない場合と、プロキシに断られた場合の原文です。

npm error gyp http GET https://nodejs.org/download/release/v22.23.4/node-v22.23.4-headers.tar.gz
npm error gyp http fetch GET https://nodejs.org/download/release/v22.23.4/node-v22.23.4-headers.tar.gz attempt 1 failed with ENOTFOUND
npm error gyp WARN install got an error, rolling back install
npm error gyp ERR! configure error
npm error gyp ERR! stack Error: This is most likely not a problem with node-gyp or the package itself and
npm error gyp ERR! stack is related to network connectivity. In most cases you are behind a proxy or have bad
npm error gyp ERR! stack network settings.

（プロキシに断られた場合）
npm error gyp http 403 https://nodejs.org/download/release/v22.23.4/node-v22.23.4-headers.tar.gz
npm error gyp ERR! configure error
npm error gyp ERR! stack Error: 403 response downloading https://nodejs.org/download/release/v22.23.4/node-v22.23.4-headers.tar.gz

直し方は3つあります。上から順に試します。

2番目の方法で、同じパッケージを入れ直した結果です。ダウンロードの行が無くなり、ビルドが通ります。

$ ls /opt/node22/include/node | head -3
common.gypi
config.gypi
cppgc
$ npm_config_nodedir=/opt/node22 npm install ../hello-addon-1.0.0.tgz
added 1 package in 1s
$ node -e "console.log(require('hello-addon').hello())"
hello from C++

3番目の方法では、devdir に版ごとのフォルダーができ、以後は --nodedir なしでも取得しません。

$ node-gyp install --tarball=./node-v22.23.4-headers.tar.gz --devdir=/work/.cache/node-gyp
gyp info it worked if it ends with ok
gyp info using node-gyp@11.5.0
gyp info using node@22.23.4 | linux | x64
gyp info ok
$ ls /work/.cache/node-gyp/22.23.4
include  installVersion
$ du -sh /work/.cache/node-gyp
63M     /work/.cache/node-gyp

devdir に書き込めないときは、警告のあとに一時的な場所で取り直します。一般ユーザー（nobody）で、root が持つ devdir を指定したときの原文です。権限の問題が続くなら、npm を sudo で動かさない設定に直します。グローバルのインストールでの権限の直し方は、関連記事「npm EACCES: permission deniedの直し方」で扱っています。

gyp WARN EACCES current user ("nobody") does not have permission to access the dev dir "/work/rodev/22.23.4"
gyp WARN EACCES attempting to reinstall using temporary dev dir "/work/nobody/.node-gyp"

Nodeの版が新しすぎる（prebuiltが無い・C++のコンパイルエラー）

この節では、Node.js を新しくした直後に gyp ERR! が出る理由と、ログの見分け方、直し方が分かります。

ネイティブモジュールの多くは、OS・CPU・Node.js の版ごとにビルド済みのバイナリ（prebuilt）を配っていて、ふだんは node-gyp を使いません。Node.js を新しくすると、その版向けの prebuilt がまだ（または、もう）無く、ソースからのビルドに切り替わります。そこで道具が無いか、ソースが新しい Node に合わないと gyp ERR! になります。

2019年の bcrypt 3.0.6 を Node.js 22 で入れた原文です。まず prebuilt が 404 になり、ソースのビルドに切り替わっています。

npm error command sh -c node-pre-gyp install --fallback-to-build
npm error node-pre-gyp http GET https://github.com/kelektiv/node.bcrypt.js/releases/download/v3.0.6/bcrypt_lib-v3.0.6-node-v127-linux-x64-glibc.tar.gz
npm error node-pre-gyp http 404 https://github.com/kelektiv/node.bcrypt.js/releases/download/v3.0.6/bcrypt_lib-v3.0.6-node-v127-linux-x64-glibc.tar.gz
npm error node-pre-gyp WARN Pre-built binaries not found for bcrypt@3.0.6 and node@22.23.4 (node-v127 ABI, glibc) (falling back to source compile with node-gyp)

道具はそろっているのでコンパイルは始まりますが、モジュールが使う nan（V8 の API の包み）が前の版で、Node.js 22 の V8 から消えた API を呼んでいるため、C++ のエラーになります。

npm error In file included from ../../nan/nan.h:173,
npm error                  from ../src/bcrypt_node.cc:1:
npm error ../../nan/nan_callbacks.h:55:23: error: 'AccessorSignature' is not a member of 'v8'
npm error    55 | typedef v8::Local<v8::AccessorSignature> Sig;
npm error ../../nan/nan_typedarray_contents.h:34:43: error: 'class v8::ArrayBuffer' has no member named 'GetContents'
npm error /opt/node22/include/node/v8-local-handle.h:269:42: error: static assertion failed: type check
...
npm error gyp ERR! build error
npm error gyp ERR! stack Error: `make` failed with exit code: 2
npm error node-pre-gyp ERR! build error
npm error node-pre-gyp ERR! node-pre-gyp -v v0.12.0
npm error node-pre-gyp ERR! not ok

このログは 176 行あり、そのうち error: は5行、残りは warning とスタックです。見るべきなのは、最初の error: の行と、そのファイルの場所（nan/・src/・/include/node/）です。エラーが node_modules の中のソースや nan で出ているなら、手元の設定ではなく「モジュールの版と Node.js の版の組み合わせ」の問題です。

同じ bcrypt でも、prebuilt を同梱した 6.0.0 は、Python・make・g++ をすべて外した環境で1秒かからずに入りました。

$ which python3 make g++        # どれも表示されない状態
$ npm install bcrypt@6.0.0
added 3 packages in 697ms
$ node -e "const b=require('bcrypt');const h=b.hashSync('pass',10);console.log(h.slice(0,7), b.compareSync('pass',h))"
$2b$10$ true
$ ls node_modules/bcrypt/prebuilds/
darwin-arm64  darwin-x64  linux-arm  linux-arm64  linux-x64  win32-arm64  win32-x64

どの版にすればよいかは、パッケージの CHANGELOG・リリースノートの「Node.js 22 対応」「prebuilt」の記述で確かめます。npm ls bcrypt で、自分が直接入れたのか、別のパッケージの依存なのかも見ます（依存なら、そのパッケージを上げます）。依存の版がぶつかって上げられないときは、関連記事「npm ERR! ERESOLVEの原因と直し方｜peer依存の読み方」で扱っています。

Node.js の版を合わせるなら、プロジェクトごとに版を切り替えられるバージョン管理ツールが便利です。nvm・fnm・Volta などの違いは、関連記事「Node.js バージョン管理｜nvm・fnm・mise・Volta比較と実測」で扱っています。

node-gypが前の版のとき（distutils・Cannot assign to read only property）

この節では、プロジェクトに残った前の版の node-gyp が、新しい Python や Node.js で動かないときの原文が分かります。

npm は自分の中に node-gyp を同梱していて、install のスクリプトはふだんそれを使います。手元の組み合わせは次のとおりでした。

ところが、パッケージが自分の依存に前の版の node-gyp を持っていると、node_modules/.bin のほうが先に使われます。node-gyp の README には「Python 3.12 以降には node-gyp v10 以降が要る」と書かれています。Python 3.12 で標準ライブラリから distutils が無くなったためです。setuptools の入っていない Python 3.13 の venv を使い、node-gyp の版だけを変えて同じモジュールをビルドしました。

$ npx node-gyp@9.4.1 rebuild --python=/work/venv313/bin/python
gyp info using node-gyp@9.4.1
gyp info find Python using Python version 3.13.18 found at "/work/venv313/bin/python"
Traceback (most recent call last):
  File ".../node-gyp/gyp/gyp_main.py", line 42, in <module>
    import gyp  # noqa: E402
  File ".../node-gyp/gyp/pylib/gyp/input.py", line 19, in <module>
    from distutils.version import StrictVersion
ModuleNotFoundError: No module named 'distutils'
gyp ERR! configure error
gyp ERR! stack Error: `gyp` failed with exit code: 1
gyp ERR! node-gyp -v v9.4.1

同じ Python でも、Ubuntu の /usr/lib/python3/dist-packages にある setuptools が見える Python（手元の /usr/local/bin/python3）では、node-gyp 8・9 も通りました。「別のパソコンでは通るのに」という差は、setuptools が見えるかどうかで出ることがあります。

node-gyp 5.1.1 を Node.js 22 で動かすと、Python より前に別のエラーで止まります。

gyp info using node-gyp@5.1.1
gyp ERR! UNCAUGHT EXCEPTION
gyp ERR! stack TypeError: Cannot assign to read only property 'cflags' of object '#<Object>'
gyp ERR! stack     at createConfigFile (.../node-gyp/lib/configure.js:118:21)
gyp ERR! node-gyp -v v5.1.1
gyp ERR! Node-gyp failed to build your package.
gyp ERR! Try to update npm and/or node-gyp and if it does not help file an issue with the package author.

直し方は、gyp ERR! node-gyp -v の版を見て、10 より前なら上げることです。npm 10 に同梱の node-gyp は 10 以降なので、npm を上げると直ることが多くあります。依存に前の版の node-gyp を持つパッケージは、そのパッケージ自体を上げるか、package.json の overrides で node-gyp の版を上書きします。npm 7 以降で npm の同梱の node-gyp を差し替える手順は、node-gyp の docs（Updating-npm-bundled-node-gyp）にあり、npm 8 までで確かめられたものとされています。

fatal error: ○○.h: No such file or directory（ライブラリのヘッダーが無い）

この節では、データベースや画像のライブラリを使うモジュールで、開発用のヘッダーが足りないときの原文と直し方が分かります。

PostgreSQL・画像処理などの C ライブラリを包んだモジュールは、そのライブラリの開発用ヘッダー（-dev・-devel のパッケージ）が要ります。pg-native が使う libpq を、PostgreSQL の開発用ヘッダーが無い環境で入れた原文です。

$ npm install libpq@1
npm error   CXX(target) Release/obj.target/addon/src/connection.o
npm error In file included from ../src/connection.cc:1:
npm error ../src/addon.h:5:10: fatal error: libpq-fe.h: No such file or directory
npm error     5 | #include <libpq-fe.h>
npm error       |          ^~~~~~~~~~~~
npm error compilation terminated.
npm error make: *** [addon.target.mk:116: Release/obj.target/addon/src/connection.o] Error 1
npm error gyp ERR! build error

Ubuntu では sudo apt install libpq-dev が直し方です。手元では apt install をせず、apt-get download libpq-dev した .deb を作業用のフォルダーに展開し、ヘッダーの場所を CPATH、ライブラリの場所を LIBRARY_PATH で g++ に教えて確かめました。

$ apt-get download libpq-dev && dpkg-deb -x libpq-dev_16.15-0ubuntu0.24.04.1_amd64.deb root
$ CPATH=$PWD/root/usr/include/postgresql LIBRARY_PATH=$PWD/root/usr/lib/x86_64-linux-gnu npm install libpq@1
added 4 packages in 9s
$ ldd node_modules/libpq/build/Release/addon.node | grep pq
        libpq.so.5 => /lib/x86_64-linux-gnu/libpq.so.5 (0x00007f015a917000)

最初の試しでは、展開したフォルダーに静的ライブラリ（libpq.a）しか見えず、ビルドは通ったのに読み込みで undefined symbol: GSS_C_NT_HOSTBASED_SERVICE になりました。ビルドが通っても require で落ちるときは、つないだライブラリ（ldd の結果）を確かめます。ふつうは apt の -dev パッケージを入れれば、この食い違いは起きません。

ヘッダー名と、入れるパッケージ名の対応はおおむね次のとおりです（Ubuntu・Debian の名前）。

直したあとに出るエラー（NODE_MODULE_VERSION・bindingsが見つからない）

この節では、ビルドは通ったあとに、実行時に出る2つの代表的なエラーと直し方が分かります。

was compiled against a different Node.js version

ネイティブモジュールは、ビルドしたときの Node.js の版（NODE_MODULE_VERSION）に結びつきます。Node.js 22 でビルドしたモジュールを、Node.js 20 で読み込んだ原文です。

$ node -v
v20.20.0
$ node -e "require('v8-addon')"
Error: The module '/work/app2/node_modules/v8-addon/build/Release/v8addon.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 127. This version of Node.js requires
NODE_MODULE_VERSION 115. Please try re-compiling or re-installing
the module (for instance, using `npm rebuild` or `npm install`).
  code: 'ERR_DLOPEN_FAILED'

$ npm rebuild v8-addon
rebuilt dependencies successfully
$ node -e "console.log(process.version, require('v8-addon').hello())"
v20.20.0 hello from V8 API

同じフォルダーに入れた、Node-API（node_api.h）だけで書いたモジュールは、Node.js 22 でビルドしたまま Node.js 20 でも動きました（hello from C++）。Node.js 公式ドキュメントは、Node-API は Node.js の版をまたいで ABI が安定していて、ある版でビルドしたモジュールを、より新しい版で再コンパイルせずに動かせることを目的にしている、と説明しています。prebuilt を同梱できるのも、この仕組みがあるからです。

Could not locate the bindings file

npm install --ignore-scripts で入れると、install のスクリプト（prebuilt の取得と node-gyp）が動かず、.node ファイルが無いまま require で失敗します。

$ npm install --ignore-scripts better-sqlite3@8.7.0
added 38 packages in 556ms
$ node -e "require('better-sqlite3')(':memory:')"
Error: Could not locate the bindings file. Tried:
 → /work/bs8i/node_modules/better-sqlite3/build/better_sqlite3.node
 → /work/bs8i/node_modules/better-sqlite3/build/Debug/better_sqlite3.node
 → /work/bs8i/node_modules/better-sqlite3/build/Release/better_sqlite3.node
 ...
 → /work/bs8i/node_modules/better-sqlite3/lib/binding/node-v127-linux-x64/better_sqlite3.node

直し方は npm rebuild better-sqlite3 で install のスクリプトを動かすことです。モジュールそのものが見つからない Cannot find module とは別のエラーで、そちらは関連記事「Node.js Cannot find moduleの原因と直し方」で扱っています。

ビルドしないで済ませる（prebuiltのある版・純JavaScript・Nodeの組み込み）

この節では、ビルドツールを入れずに gyp ERR! を避ける方法と、ビルドする場合との時間の差が分かります。

gyp ERR! のいちばん確実な直し方は、ビルドをしないことです。選べる方法は3つあります。

• prebuilt のある版を使う：bcrypt 6.0.0 は prebuilds フォルダーに OS ごとのバイナリを同梱し、install は node-gyp-build が選ぶだけです。better-sqlite3 は prebuild-install で GitHub のリリースから取得します。
• 純 JavaScript の代替を使う：bcrypt なら bcryptjs。ネイティブのビルドが無く、どの OS でも同じように入ります。
• Node.js の組み込みを使う：SQLite なら node:sqlite（Node.js 22 では ExperimentalWarning が出ます）。

better-sqlite3 の前の版（8.7.0）は Node.js 22 向けの prebuilt が無く、C コンパイラの無い環境では gyp ERR! になりました。新しい版（12.11.1）は同じ環境で1秒で入っています。

$ npm install better-sqlite3@8.7.0          # cc が無い環境
npm error command sh -c prebuild-install || node-gyp rebuild --release
npm error prebuild-install warn install No prebuilt binaries found (target=22.23.4 runtime=node arch=x64 libc= platform=linux)
npm error make: cc: No such file or directory
npm error gyp ERR! build error

$ npm install --foreground-scripts better-sqlite3@12   # Python・make・g++ なし
> better-sqlite3@12.11.1 install
> prebuild-install || node-gyp rebuild --release
added 38 packages in 942ms
$ node -e "const D=require('better-sqlite3');console.log(new D(':memory:').prepare('select sqlite_version() v').get())"
{ v: '3.53.2' }

$ node -e "const {DatabaseSync}=require('node:sqlite');console.log(new DatabaseSync(':memory:').prepare('select sqlite_version() v').get())"
[Object: null prototype] { v: '3.53.4' }
(node:16973) ExperimentalWarning: SQLite is an experimental feature and might change at any time

同じプロジェクトで、install の時間と、ハッシュ1回の時間（コスト10、5回の平均、3回測った範囲）を測りました。

純 JS の bcryptjs は、ネイティブの bcrypt より1回あたり2割ほど遅い結果でしたが、ビルドの失敗とは無縁です。パスワードのハッシュのコストの決め方は、関連記事「パスワードのハッシュ化｜bcrypt・Argon2の推奨値と実測・移行コード」で扱っています。

• 1どのパッケージがビルドしているかを npm ls で確かめたログの path の名前を npm ls に渡す。直接の依存でなければ親を上げる
• 2今の Node 向けの prebuilt がある版を調べたリリースノート・prebuilds フォルダー・GitHub のリリースの添付ファイルで確かめる
• 3純 JS・組み込みの代替を検討したbcryptjs・node:sqlite のように、ビルドの無い選択肢がないか
• 4CI・Docker でも同じ Node の版にそろえた手元と CI で版が違うと、片方だけ prebuilt が無く失敗する

OS別の直し方（Windows・Mac・Linux・Docker）

この節では、OS ごとに、ビルドツールの入れ方と起きやすい gyp ERR! が分かります。

Linux は手元で確かめた手順、Windows・Mac は node-gyp の README と Microsoft Learn で確かめた範囲です。

Windows

node-gyp の README は、Windows では Chocolatey での choco install python visualstudio2026-workload-vctools -y、または Python と Visual Studio を手で入れる方法を案内しています。Visual Studio 2019 以降では「Desktop development with C++」のワークロードを選ぶ、とされています（Microsoft Learn の日本語版では「C++ によるデスクトップ開発」）。ARM64 の Windows では、ARM64 用の Visual C++ のコンパイラとライブラリ、ATL も要るとされています。--msvs_version は Visual Studio の版を指定するオプションで、README の説明では npm から動かすときには通常要りません。

Windows で Linux と同じ手順を使いたい場合は、WSL2 の Ubuntu の中で Node.js とビルドツールを入れる方法もあります。関連記事「WSL2環境構築｜Ubuntu開発環境をコマンドだけで整える手順」で扱っています。

Mac

README は、Python と Xcode Command Line Tools（clang・clang++・make）を求め、xcode-select --install で入れる、または Xcode の開発者ツールのメニューから入れるとしています。macOS を大きく更新したあとに gyp ERR! が出始めたら、まず Command Line Tools が入っているかを確かめます。Apple シリコンの Mac で prebuilt が無いモジュールは、ソースからのビルドになる点も Linux と同じです。

Docker・CI

node:22-slim のような小さなイメージには、python3・make・g++ が入っていないことがあります。ビルドの段だけで道具を入れ、できた node_modules を実行用の段へ写すと、実行用のイメージを小さく保てます。prebuilt は glibc 用と musl（Alpine）用で別になっていることが多く、bcrypt 6.0.0 の prebuilds でも linux-x64 の下に bcrypt.glibc.node と bcrypt.musl.node の2つが入っていました。

よくあるエラーと判断表

この節では、似たエラー文の見分け方と、状況ごとにどの直し方を選ぶかが分かります。

よくあるエラー／つまずき

判断表

よくある質問

この節では、gyp ERR! について検索の多い疑問に短く答えます。

Q. gyp ERR! が出ても、そのまま使えますか？
A. npm install が「npm error code 1」で終わったなら、そのパッケージは入っていません。gyp WARN だけで最後に added … と出ていれば、入っています。

Q. npm cache clean --force で直りますか？
A. キャッシュの破損が原因のときだけです。手元で再現した14種類の失敗は、どれもキャッシュとは関係なく、道具・ヘッダー・版を直して解決しました。

Q. sudo npm install で直りますか？
A. 権限の問題（EACCES）でなければ直りません。sudo で動かすと devdir やキャッシュが root の持ち物になり、次から一般ユーザーで EACCES になる原因にもなります。

Q. Python 2 が要るのですか？
A. 現在の node-gyp は Python 3 を使います。Python 2 を求めるログが出るなら、node-gyp 5 以前のような前の版が使われているので、npm かパッケージを上げます。

Q. node-gyp をグローバルに入れれば直りますか？
A. npm は同梱の node-gyp を使うため、グローバルに入れても install のスクリプトには使われないことが多いです。node-gyp の docs も、グローバルに入れても npm の同梱の版は変わらないとしています。

Q. どのパッケージがネイティブモジュールか分かりますか？
A. node_modules の中で binding.gyp を探すと分かります。find node_modules -name binding.gyp を実行すると、ビルドする可能性のあるパッケージが一覧になります。

Q. yarn・pnpm でも同じエラーになりますか？
A. なります。どれも install のスクリプトで node-gyp を動かすため、原因と直し方は同じです。install のスクリプトが動かない設定のときは、前の節の bindings が見つからないエラーになります。

Q. M1・M2 の Mac だけで失敗します。
A. arm64 向けの prebuilt が無いパッケージは、ソースからのビルドになります。Command Line Tools を入れたうえで、パッケージを arm64 対応の版へ上げるのが確実です。

Q. Node.js を一番新しい版にすべきですか？
A. ネイティブモジュールを使うプロジェクトでは、LTS の版にそろえると prebuilt が見つかりやすくなります。新しい版は、使うモジュールが対応を発表してから上げると失敗が減ります。

まとめ

この節では、記事の要点を5つにまとめます。

• gyp ERR! は、ネイティブモジュールを手元でビルドしようとして失敗したという node-gyp のエラー。stack Error の1行目と、その上の error: を読む。
• 道具の不足は原文で見分けられる。find Python は Python、not found: make は make、g++: No such file は C++ コンパイラ、cannot execute 'as' は binutils。
• ヘッダーの取得の失敗（ENOTFOUND・403）は、プロキシの設定か、--nodedir・--tarball でローカルのヘッダーを使うと直る。
• Node を上げた直後の失敗は、prebuilt が無くソースのビルドに落ちたことが多い。モジュールを対応版へ上げるか、Node を LTS に合わせる。node-gyp は 10 以降を使う。
• いちばん確実なのはビルドしないこと。prebuilt を同梱した版（bcrypt 6 は道具なしで 0.8 秒）、純 JS の代替、Node の組み込みを先に検討する。

参考・出典

この節では、記事の中で確かめた公式の情報源を挙げます（確認日 2026年11月6日）。

• node-gyp（GitHub・README：Installation、Configuring Python Dependency、Command Options）：https://github.com/nodejs/node-gyp
• node-gyp docs「Updating-npm-bundled-node-gyp」：https://github.com/nodejs/node-gyp/blob/main/docs/Updating-npm-bundled-node-gyp.md
• node-gyp docs「Force-npm-to-use-global-node-gyp」：https://github.com/nodejs/node-gyp/blob/main/docs/Force-npm-to-use-global-node-gyp.md
• npm Docs「scripts」（binding.gyp と node-gyp rebuild、--foreground-scripts）：https://docs.npmjs.com/cli/v10/using-npm/scripts
• Node.js Docs「Node-API」（ABI の安定性）：https://nodejs.org/api/n-api.html
• Microsoft Learn「Visual Studio に C および C++ サポートをインストールする」：https://learn.microsoft.com/ja-jp/cpp/build/vscpp-step-0-installation

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。