Build toolchain compatibility with Visual Studio 2026

[MikeMcC399]

Current situation

BUILDING > Supported toolchains for Windows lists the following compatible Visual Studio versions:

Node.js branch	Windows Supported toolchain	Node.js version	npm version
v20.x	Visual Studio >= 2019 with the Windows 10 SDK on a 64-bit host	20.19.6	10.8.2
v22.x	Visual Studio >= 2022 with the Windows 10 SDK on a 64-bit host	22.21.2	10.9.4
v24.x	Visual Studio >= 2022 with the Windows 10 SDK on a 64-bit host	24.11.1	11.6.2
v25.x	Visual Studio >= 2022 with the Windows 10 SDK on a 64-bit host	25.2.1	11.6.2

Compatibility with Visual Studio 2026 requires node-gyp@12.1.0 which is bundled in npm@11.6.3.

Expected

"Visual Studio >=" can only be used where there is compatibility to Visual Studio 2026. This however requires a minimum of npm@11.6.3. PR #60853 proposes upgrading npm to 11.6.4 and this can be expected to be applied on Node.js 24.x and 25.x

If Node.js 20.x and 22.x stay with npm 10.x, then the supported toolchain would need to exclude Visual Studio 2026 and be changed to:

Node.js branch	Windows Supported toolchain
v20.x	Visual Studio 2019 or 2022 with the Windows 10 SDK on a 64-bit host
v22.x	Visual Studio 2022 with the Windows 10 SDK on a 64-bit host

Reference

• Visual Studio 2026 announcement, Nov 11, 2025
• Release notes:
  • node-gyp@12.1.0
  • npm@11.6.3
• PR feat: Support for Visual Studio 2026 (18.x) to enable node-gyp to work with the latest Visual Studio preview and release versions. node-gyp#3240

[marco-ippolito]

I'm pretty confident that Node.js 20 and 22 will stay with npm 10. I think changing the toolchain requirements is a breaking change

[richardlau]

cc @nodejs/platform-windows

FWIW node-gyp only applies to addons (including building the addon and node-api tests).

Building Node.js itself relies on the copy of gyp-next in tools/gyp (which is separate from whatever is in npm). I don't know if that can be safely updated in Node.js 20 and 22 without breaking something else (e.g. minimum Python version).

[MikeMcC399]

@richardlau

I have not tried to build Node.js from source on Windows and I may have misinterpreted the information in the toolchain compatibility table.

I noticed the problem trying to install the npm package cpu-features@0.0.10 using Node.js 22.21.1 (with npm 10.9.4, Python 3.14.0) on Windows 11 25H2 and I assumed this would also apply to Node.js itself.

If this isn't relevant for the core of Node.js, then please feel free to close the issue.

Repro steps for npm module needing node-gyp

Install Visual Studio Build Tools 2026 18.0.2 with workload "Desktop development with C++" (see docs https://learn.microsoft.com/en-us/visualstudio/releases/2026/release-history).

In Git Bash:

cd $(mktemp -d)
npm install cpu-features

$ cd $(mktemp -d)
npm install cpu-features
npm error code 1
npm error path C:\Users\mikem\AppData\Local\Temp\tmp.AyQiFSDsdu\node_modules\cpu-features
npm error command failed
npm error command C:\WINDOWS\system32\cmd.exe /d /s /c node buildcheck.js > buildcheck.gypi && node-gyp rebuild
npm error gyp info it worked if it ends with ok
npm error gyp info using node-gyp@11.2.0
npm error gyp info using node@22.21.1 | win32 | x64
npm error gyp info find Python using Python version 3.14.0 found at "C:\Python314\python.exe"
npm error gyp ERR! find VS
npm error gyp ERR! find VS msvs_version not set from command line or npm config
npm error gyp ERR! find VS VCINSTALLDIR not set, not running in VS Command Prompt
npm error gyp ERR! find VS could not use PowerShell to find Visual Studio 2017 or newer, try re-running with '--loglevel silly' for more details.
npm error gyp ERR! find VS
npm error gyp ERR! find VS Failure details: undefined
npm error gyp ERR! find VS unknown version "undefined" found at "C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools"
npm error gyp ERR! find VS could not find a version of Visual Studio 2017 or newer to use
npm error gyp ERR! find VS not looking for VS2017 as it is only supported up to Node.js 21
npm error gyp ERR! find VS not looking for VS2017 as it is only supported up to Node.js 21
npm error gyp ERR! find VS not looking for VS2017 as it is only supported up to Node.js 21
npm error gyp ERR! find VS not looking for VS2015 as it is only supported up to Node.js 18
npm error gyp ERR! find VS not looking for VS2013 as it is only supported up to Node.js 8
npm error gyp ERR! find VS
npm error gyp ERR! find VS **************************************************************
npm error gyp ERR! find VS You need to install the latest version of Visual Studio
npm error gyp ERR! find VS including the "Desktop development with C++" workload.
npm error gyp ERR! find VS For more information consult the documentation at:
npm error gyp ERR! find VS https://github.com/nodejs/node-gyp#on-windows
npm error gyp ERR! find VS **************************************************************
npm error gyp ERR! find VS
npm error gyp ERR! configure error
npm error gyp ERR! stack Error: Could not find any Visual Studio installation to use
npm error gyp ERR! stack at VisualStudioFinder.fail (C:\Users\mikem\AppData\Local\nvm\v22.21.1\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:118:11)
npm error gyp ERR! stack at VisualStudioFinder.findVisualStudio (C:\Users\mikem\AppData\Local\nvm\v22.21.1\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:74:17)
npm error gyp ERR! stack at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
npm error gyp ERR! stack at async createBuildDir (C:\Users\mikem\AppData\Local\nvm\v22.21.1\node_modules\npm\node_modules\node-gyp\lib\configure.js:112:18)
npm error gyp ERR! stack at async run (C:\Users\mikem\AppData\Local\nvm\v22.21.1\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js:81:18)
npm error gyp ERR! System Windows_NT 10.0.26200
npm error gyp ERR! command "C:\\nvm4w\\nodejs\\node.exe" "C:\\Users\\mikem\\AppData\\Local\\nvm\\v22.21.1\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild"
npm error gyp ERR! cwd C:\Users\mikem\AppData\Local\Temp\tmp.AyQiFSDsdu\node_modules\cpu-features
npm error gyp ERR! node -v v22.21.1
npm error gyp ERR! node-gyp -v v11.2.0
npm error gyp ERR! not ok

[targos]

The patch that adds support for VS 2026 in gyp-next is quite small. We could probably backport it

[MikeMcC399]

The patch that adds support for VS 2026 in gyp-next is quite small. We could probably backport it

It sounds like this would be #60645

[targos]

I'm thinking about nodejs/gyp-next@cb13bbc

[MikeMcC399]

There are two different issues mixed up in this issue submission:

1. installing npm packages requiring rebuild with node-gyp
2. building Node.js from source

I'm going to close this issue and re-submit so that it only covers building Node.js from source

[MikeMcC399]

Continued in replacement issue #60869