nodejs/node · error · RuntimeError

This script does not support running with cygwin python.

Error message

This script does not support running with cygwin python.

What it means

Raised at the top of main() in Node's tools/build_addons.py when sys.platform == 'cygwin', because the addon-build script does not support running under Cygwin Python (path handling, MSBuild invocation, and node-gyp behave incorrectly under the Cygwin POSIX layer on Windows).

Source

Thrown at tools/build_addons.py:108

    codes = executor.map(node_gyp_rebuild, test_dirs)
    return 0 if all(code == 0 for code in codes) else 1

def get_default_out_dir(args):
  default_out_dir = os.path.join('out', args.config)
  if not args.is_win:
    # POSIX platforms only have one out dir.
    return default_out_dir
  # On Windows depending on the args of GYP and configure script, the out dir
  # could be 'out/Release', 'out/Debug' or just 'Release' or 'Debug'.
  if os.path.exists(default_out_dir):
    return default_out_dir
  if os.path.exists(args.config):
    return args.config
  raise RuntimeError('Cannot find out dir, did you run build?')

def main():
  if sys.platform == 'cygwin':
    raise RuntimeError('This script does not support running with cygwin python.')

  parser = argparse.ArgumentParser(
      description='Install headers and rebuild child directories')
  parser.add_argument('target', help='target directory to build addons')
  parser.add_argument('--headers-dir',
                      help='path to node headers directory, if not specified '
                           'new headers will be generated for building',
                      default=None)
  parser.add_argument('--out-dir', help='path to the output directory',
                      default=None)
  parser.add_argument('--loglevel', help='loglevel of node-gyp',
                      default='silent')
  parser.add_argument('--skip-tests', help='skip building tests',
                      default='')
  parser.add_argument('--only-tests', help='only build tests in the list',
                      default='')
  parser.add_argument('--node-gyp', help='path to node-gyp script',
                      default='deps/npm/node_modules/node-gyp/bin/node-gyp.js')

View on GitHub (pinned to 1b2de5e052)

Solutions

Run the script with native Windows CPython (e.g. py -3 tools/build_addons.py, or the python.exe from python.org) so sys.platform is 'win32'.
Run from cmd.exe or PowerShell rather than a Cygwin bash session.
Remove Cygwin Python from PATH precedence if native Python should be the default.

Example fix

# before (Cygwin python)
python tools/build_addons.py ./myaddon
# after (native Windows python)
py -3 tools/build_addons.py ./myaddon

Defensive patterns

Strategy: validation

Validate before calling

import sys
if sys.platform == 'cygwin':
    raise SystemExit('Use native Windows Python (py -3), not Cygwin Python.')

Type guard

def is_native_windows_python() -> bool:
    import sys
    return sys.platform == 'win32'

Try / catch

null

Prevention

Run the script with native CPython (py -3 / python.exe from python.org).
Invoke from cmd.exe or PowerShell rather than a Cygwin shell.
Adjust PATH so native Python takes precedence over Cygwin Python.

When it happens

Trigger: Invoking python tools/build_addons.py from a Cygwin shell/terminal where the python on PATH is the Cygwin build (sys.platform reports 'cygwin').

Common situations: A developer on Windows whose default python in the shell is Cygwin's rather than the native CPython; running the script through a Cygwin bash login shell.

Related errors

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/a88811f3df17ed31. Report an issue: GitHub.