nodejs/node · error · ValueError

Could not locate Visual Studio installation.

Error message

Could not locate Visual Studio installation.

What it means

When neither override mechanism nor fallback resolves a Visual Studio install, _GetVisualStudioVersion raises ValueError('Could not locate Visual Studio installation.'). _DetectVisualStudioVersions returned an empty list for the requested version key, and allow_fallback is False, so gyp refuses to silently pick a wrong toolchain. (When allow_fallback is True and version=='auto', gyp falls back to VS2005 or the requested version with a None path.)

Source

Thrown at tools/gyp/pylib/gyp/MSVSVersion.py:601

        "2015": ("14.0",),
        "2017": ("15.0",),
        "2019": ("16.0",),
        "2022": ("17.0",),
        "2026": ("18.0",),
    }
    if override_path := os.environ.get("GYP_MSVS_OVERRIDE_PATH"):
        msvs_version = os.environ.get("GYP_MSVS_VERSION")
        if not msvs_version:
            raise ValueError(
                "GYP_MSVS_OVERRIDE_PATH requires GYP_MSVS_VERSION to be "
                "set to a particular version (e.g. 2010e)."
            )
        return _CreateVersion(msvs_version, override_path, sdk_based=True)
    version = str(version)
    versions = _DetectVisualStudioVersions(version_map[version], "e" in version)
    if not versions:
        if not allow_fallback:
            raise ValueError("Could not locate Visual Studio installation.")
        if version == "auto":
            # Default to 2005 if we couldn't find anything
            return _CreateVersion("2005", None)
        else:
            return _CreateVersion(version, None)
    return versions[0]

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Install Visual Studio (or the standalone Build Tools) for the requested version, including the C++ workload.
2. Set GYP_MSVS_VERSION to a version that is actually installed, or 'auto' to let gyp detect.
3. Set GYP_MSVS_OVERRIDE_PATH + GYP_MSVS_VERSION to point at a known install location.
4. Re-run with allow_fallback enabled if a best-effort match is acceptable.

Example fix

# before: no VS, version pinned
set GYP_MSVS_VERSION=2019
python gyp

# after: install Build Tools 2022, then auto-detect
set GYP_MSVS_VERSION=auto
python gyp

import subprocess
def vs_installed():
    try:
        subprocess.check_output(['vswhere', '-latest', '-property', 'installationPath'], stderr=subprocess.DEVNULL)
        return True
    except Exception:
        return False
if not vs_installed():
    raise SystemExit('No Visual Studio detected. Install VS or Build Tools with the C++ workload.')

def visual_studio_available(version: str = 'auto') -> bool:
    try:
        _GetVisualStudioVersion(version)
        return True
    except Exception:
        return False

try:
    vs = _GetVisualStudioVersion('2019')
except ValueError:
    vs = _GetVisualStudioVersion('auto', allow_fallback=True)  # best-effort fallback

When it happens

Trigger: Running gyp -f msvs on a machine with no Visual Studio installed; requesting a specific version (e.g. GYP_MSVS_VERSION=2019) that isn't present and fallback is disabled; registry/where/wmic detection all coming up empty.

Common situations: Clean CI Windows image without Build Tools; VS installed only for a different user account; bit-ness mismatch (only x86 VS detected but x64 requested).

Related errors

• %s is missing - make sure VC++ tools are installed.
• AddFileConfig: file "%s" not in project.
• GYP_MSVS_OVERRIDE_PATH requires GYP_MSVS_VERSION to be set t
• Appending "%s" to a non-list setting "%s" for tool "%s" is n
• Invalid MSVS guid: "%s". Must match regex: "%s".

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