gyp: 'Undefined variable android_ndk_path' when building native modules on Android (Termux) without NDK
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 10.7k
- Forks
- 1.9k
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 5
Description
Describe the bug
Building any native module with node-gyp on Android (Termux) fails with an unhelpful gyp error, even though a working toolchain (clang) is installed:
gyp: Undefined variable android_ndk_path in binding.gyp while trying to load binding.gyp
Environment: Termux on Android 15 (aarch64), Node v26.4.0, npm 12.0.2, clang 21, no NDK (Android NDK is not practical to install on Termux; the system provides its own bionic toolchain).
Root cause chain
- Termux's python3 reports
sys.platform == "android", so gyp selects theandroidflavor. - node-gyp does not use the headers shipped with the Node package (
/usr/include/node/common.gypi, which Termux's packaging already patches for this exact issue); instead it downloads the official Node headers from nodejs.org into~/.cache/node-gyp/<version>/. - The official
common.gypihas anOS == "android"branch that references<(android_ndk_path)/sources/android/cpufeatures. On a plain Android system with no NDK,android_ndk_pathis undefined and gyp aborts with the message above — it reads as an internal gyp bug rather than a missing-NDK situation.
Expected behavior
- Either node-gyp should prefer locally installed Node headers when present (Termux's
/usr/include/nodeis a valid, already-patched header set), or - on Android without an NDK, emit an actionable error (e.g. "building native modules on Android requires the Android NDK, or use the system toolchain via
--nodedir=/usr/include/node") instead ofUndefined variable android_ndk_path.
Workaround (used successfully)
Patch ~/.cache/node-gyp/26.4.0/include/node/common.gypi: in the OS == "android" branch, replace -I<(android_ndk_path)/sources/android/cpufeatures with the system include dir. After that, node-pty and other native modules compile and link fine against the Termux bionic toolchain.
This affects every Termux user who builds native npm modules (node-pty, sharp, koffi, etc.).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the failure on Termux and trace node-gyp's header selection into the cached common.gypi, especially the OS == "android" branch and its android_ndk_path reference. Compare that path with the patched /usr/include/node headers and the --nodedir workaround; done means Android without an NDK no longer produces the misleading undefined-variable failure and the chosen supported path has coverage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, nodejs, python
- Domain
- build-system, mobile-dev, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100