MSVC `/external:I` are not treated as system include directories

[huangqinjin]

Environment

• OS and Version: Windows 10
• VS Code Version: 1.109.2
• C/C++ Extension Version: 1.30.5

Bug Summary

/external:I in compilerArgs for MSVC are not treated as system include directories as shown in C/C++ Diagnostic:

    Include paths:
        include: C:\tmp\.vscode

But for clang++ -isystem, it is correctly detected as system include:

    Include paths:
        system include (isystem): C:\tmp\.vscode

clang-cl -imsvc as well:

    Include paths:
        system include: C:\Program Files\LLVM\lib\clang\21\include
        system include: C:\tmp\.vscode

Configuration and Logs

C/C++ Diagnostic for MSVC /external:I

-------- Diagnostics - 2026/2/13 00:47:56
Version: 1.30.5
Current Configuration:
{
    "name": "Test",
    "intelliSenseMode": "windows-msvc-x64",
    "compilerArgs": [
        "/external:I${workspaceFolder}/.vscode"
    ],
    "compilerPathIsExplicit": false,
    "cStandardIsExplicit": false,
    "cppStandardIsExplicit": false,
    "intelliSenseModeIsExplicit": true,
    "recursiveIncludesReduceIsExplicit": false,
    "recursiveIncludesPriorityIsExplicit": false,
    "recursiveIncludesOrderIsExplicit": false,
    "windowsSdkVersion": "10.0.26100.0",
    "cStandard": "c17",
    "cppStandard": "c++17",
    "mergeConfigurations": false,
    "recursiveIncludes": {},
    "compilerPath": "C:\\Program Files\\Microsoft Visual Studio\\18\\Enterprise\\VC\\Tools\\MSVC\\14.50.35717\\bin\\Hostx64\\x64\\cl.exe",
    "browse": {
        "limitSymbolsToIncludedHeaders": true
    }
}
Additional Tracked Settings:
{
    "editorTabSize": 4,
    "editorInsertSpaces": true,
    "editorAutoClosingBrackets": "languageDefined",
    "filesEncoding": "utf8",
    "filesAssociations": {},
    "filesExclude": {
        "**/.git": true,
        "**/.svn": true,
        "**/.hg": true,
        "**/.DS_Store": true,
        "**/Thumbs.db": true,
        "**/.classpath": true,
        "**/.project": true,
        "**/.settings": true,
        "**/.factorypath": true
    },
    "filesAutoSaveAfterDelay": false,
    "editorInlayHintsEnabled": true,
    "editorParameterHintsEnabled": true,
    "searchExclude": {
        "**/node_modules": true,
        "**/bower_components": true,
        "**/*.code-search": true
    },
    "workbenchSettingsEditor": "ui"
}
cpptools version (native): 1.30.5.0
Current database path: C:\USERS\HUANGQINJIN\APPDATA\LOCAL\MICROSOFT\VSCODE-CPPTOOLS\90D20250051651E1D809C1C7E0C52070\.BROWSE.VC.DB
Translation Unit Mappings:
[ C:\tmp\main.cpp - source TU]:
Translation Unit Configurations:
[ C:\tmp\main.cpp ]
    Process ID: 2948
    Memory Usage: 50 MB
    Compiler Path: C:\Program Files\Microsoft Visual Studio\18\Enterprise\VC\Tools\MSVC\14.50.35717\bin\Hostx64\x64\cl.exe
    Include paths:
        include: C:\tmp\.vscode
        system include: C:\Program Files\Microsoft Visual Studio\18\Enterprise\VC\Tools\MSVC\14.50.35717\include
        system include: C:\Program Files\Microsoft Visual Studio\18\Enterprise\VC\Tools\MSVC\14.50.35717\atlmfc\include
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\um
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\ucrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\shared
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\winrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\cppwinrt
    Standard Version: ms_c++17
    IntelliSense Mode: windows-msvc-x64
Total Memory Usage: 50 MB

------- Workspace parsing diagnostics -------
Number of files discovered (not excluded): 5348

C/C++ Diagnostic for clang++ -isystem

-------- Diagnostics - 2026/2/13 00:52:26
Version: 1.30.5
Current Configuration:
{
    "name": "Test",
    "compilerPath": "C:\\Program Files\\LLVM\\bin\\clang++.exe",
    "compilerArgs": [
        "-isystem${workspaceFolder}/.vscode"
    ],
    "compilerPathIsExplicit": true,
    "cStandardIsExplicit": false,
    "cppStandardIsExplicit": false,
    "intelliSenseModeIsExplicit": false,
    "recursiveIncludesReduceIsExplicit": false,
    "recursiveIncludesPriorityIsExplicit": false,
    "recursiveIncludesOrderIsExplicit": false,
    "compilerPathInCppPropertiesJson": "C:\\Program Files\\LLVM\\bin\\clang++.exe",
    "mergeConfigurations": false,
    "recursiveIncludes": {},
    "browse": {
        "limitSymbolsToIncludedHeaders": true
    }
}
Additional Tracked Settings:
{
    "editorTabSize": 4,
    "editorInsertSpaces": true,
    "editorAutoClosingBrackets": "languageDefined",
    "filesEncoding": "utf8",
    "filesAssociations": {},
    "filesExclude": {
        "**/.git": true,
        "**/.svn": true,
        "**/.hg": true,
        "**/.DS_Store": true,
        "**/Thumbs.db": true,
        "**/.classpath": true,
        "**/.project": true,
        "**/.settings": true,
        "**/.factorypath": true
    },
    "filesAutoSaveAfterDelay": false,
    "editorInlayHintsEnabled": true,
    "editorParameterHintsEnabled": true,
    "searchExclude": {
        "**/node_modules": true,
        "**/bower_components": true,
        "**/*.code-search": true
    },
    "workbenchSettingsEditor": "ui"
}
cpptools version (native): 1.30.5.0
Current database path: C:\USERS\HUANGQINJIN\APPDATA\LOCAL\MICROSOFT\VSCODE-CPPTOOLS\90D20250051651E1D809C1C7E0C52070\.BROWSE.VC.DB
Translation Unit Mappings:
[ C:\tmp\main.cpp - source TU]:
Translation Unit Configurations:
[ C:\tmp\main.cpp ]
    Process ID: 15408
    Memory Usage: 51 MB
    Compiler Path: C:\Program Files\LLVM\bin\clang++.exe
    Include paths:
        system include (isystem): C:\tmp\.vscode
        system include: C:\Program Files\LLVM\lib\clang\21\include
        system include: C:\Program Files\Microsoft Visual Studio\18\Enterprise\VC\Tools\MSVC\14.50.35717\include
        system include: C:\Program Files\Microsoft Visual Studio\18\Enterprise\VC\Tools\MSVC\14.50.35717\atlmfc\include
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\ucrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\shared
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\um
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\winrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\cppwinrt
    Standard Version: c++14
    IntelliSense Mode: windows-clang-x64
    Other Flags:
        --clang
        --clang_version=210108
        --ms_compatibility
Total Memory Usage: 51 MB

------- Workspace parsing diagnostics -------
Number of files discovered (not excluded): 6459
Number of files parsed: 1

C/C++ Diagnostic for clang-cl -imsvc

-------- Diagnostics - 2026/2/13 00:53:17
Version: 1.30.5
Current Configuration:
{
    "name": "Test",
    "compilerPath": "C:\\Program Files\\LLVM\\bin\\clang-cl.exe",
    "compilerArgs": [
        "-imsvc${workspaceFolder}/.vscode"
    ],
    "compilerPathIsExplicit": true,
    "cStandardIsExplicit": false,
    "cppStandardIsExplicit": false,
    "intelliSenseModeIsExplicit": false,
    "recursiveIncludesReduceIsExplicit": false,
    "recursiveIncludesPriorityIsExplicit": false,
    "recursiveIncludesOrderIsExplicit": false,
    "compilerPathInCppPropertiesJson": "C:\\Program Files\\LLVM\\bin\\clang-cl.exe",
    "mergeConfigurations": false,
    "recursiveIncludes": {},
    "browse": {
        "limitSymbolsToIncludedHeaders": true
    }
}
Additional Tracked Settings:
{
    "editorTabSize": 4,
    "editorInsertSpaces": true,
    "editorAutoClosingBrackets": "languageDefined",
    "filesEncoding": "utf8",
    "filesAssociations": {},
    "filesExclude": {
        "**/.git": true,
        "**/.svn": true,
        "**/.hg": true,
        "**/.DS_Store": true,
        "**/Thumbs.db": true,
        "**/.classpath": true,
        "**/.project": true,
        "**/.settings": true,
        "**/.factorypath": true
    },
    "filesAutoSaveAfterDelay": false,
    "editorInlayHintsEnabled": true,
    "editorParameterHintsEnabled": true,
    "searchExclude": {
        "**/node_modules": true,
        "**/bower_components": true,
        "**/*.code-search": true
    },
    "workbenchSettingsEditor": "ui"
}
cpptools version (native): 1.30.5.0
Current database path: C:\USERS\HUANGQINJIN\APPDATA\LOCAL\MICROSOFT\VSCODE-CPPTOOLS\90D20250051651E1D809C1C7E0C52070\.BROWSE.VC.DB
Translation Unit Mappings:
[ C:\tmp\main.cpp - source TU]:
Translation Unit Configurations:
[ C:\tmp\main.cpp ]
    Process ID: 24416
    Memory Usage: 51 MB
    Compiler Path: C:\Program Files\LLVM\bin\clang-cl.exe
    Include paths:
        system include: C:\Program Files\LLVM\lib\clang\21\include
        system include: C:\tmp\.vscode
        system include: C:\Program Files\Microsoft Visual Studio\18\Enterprise\VC\Tools\MSVC\14.50.35717\include
        system include: C:\Program Files\Microsoft Visual Studio\18\Enterprise\VC\Tools\MSVC\14.50.35717\atlmfc\include
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\ucrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\shared
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\um
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\winrt
        system include: C:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\cppwinrt
    Standard Version: c++14
    IntelliSense Mode: windows-clang-x64
    Other Flags:
        --clang
        --clang_version=210108
        --ms_compatibility
Total Memory Usage: 51 MB

------- Workspace parsing diagnostics -------
Number of files discovered (not excluded): 6459
Number of files parsed: 1

[Colengms]

Hi @huangqinjin . My understanding is that /external:I can add an include path (if /external:W# is also specified) to be considered "external" for the purpose of external header diagnostics only, not specify that the include path should be an additional "system" include path (like gcc and clang's -isystem arg). I don't believe MSVC provides an argument that would allow the caller to add a system include path.

The following tests use multiple include paths containing a header of the same name.

cl /nologo /external:I path_A /c test_include_paths.cpp
-- cl : Command line warning D9007 : '/external:I' requires '/external:W'; option ignored
-- Header is not found

The following imply that an include path is added by /external:I, but the first example would have found path B if /external:I had made path_A a system include path, as user include paths take priority over system include paths (and priority is otherwise from left-to-right). If /external:I had specified a different priority than /I, these command lines would have the same result - path B.

cl /nologo /external:W4 /external:I path_A /I path_B /c test_include_paths.cpp
-- Finds path A.

cl /nologo /external:W4 /I path_B /external:I path_A /c test_include_paths.cpp 
-- Finds path B.

Unfortunately, it looks like clang-cl folks made a similar incorrect assumption about the behavior of the argument:

clang-cl  /nologo /external:I path_A /c test_include_paths.cpp
 -- Finds path A.

clang-cl /nologo /external:W4 /external:I path_A /I path_B /c test_include_paths.cpp
 -- Finds path B.

clang-cl /nologo /external:W4 /I path_B /external:I path_A /c test_include_paths.cpp
 -- Finds path B.

Since clang-cl is supposed to mirror the behavior of MSVC args, this looks like a clang-cl bug. Though, we could have cpptools reflect the behavior of clang-cl when clang-cl is specified. (If they fix this, we could potentially do a version check to reflect the proper expected behavior.)

[Colengms]

I opened an issue against LLVM: llvm/llvm-project#181294