'SDL2/SDL.h' file not found when trying to run script on MacOS vsCode
18:37 12 Jan 2026

I'm trying to get SDL2 to work inside VScode so I can start learning it. I don't really know how VSCode launch, tasks, property json etc works, and I haven't found much online for how to set up SDL2 in VScode on mac precisely, so I had to use chatgpt. Big shocker, it doesn't work properly and I can't get it to fix the problem, and trying to include sdl2.h in any script shows the error "'SDL2/SDL.h' file not found" error in the editor. I tried using this repo(https://github.com/mahanmi/SDL2-on-mac/) to pre-set it up, but the exact same issue occurs with that as well. My test script, c_cpp_properties.json, launch.json, and tasks.json are below:

c_cpp_properties.json:

{
    "version": 4,
    "configurations": [
        {
            "name": "macOS-Clang",
            "includePath": [
                "${workspaceFolder}/**",
                "/opt/homebrew/include"
            ],
            "browse": {
                "path": [
                    "${workspaceFolder}/**",
                    "/opt/homebrew/include"
                ],
                "limitSymbolsToIncludedHeaders": true
            },
            "defines": [],
            "macFrameworkPath": [
                "/System/Library/Frameworks",
                "/Library/Frameworks"
            ],
            "compilerPath": "/usr/bin/clang++",
            "cStandard": "c17",
            "cppStandard": "c++20",
            "intelliSenseMode": "macos-clang-arm64"
        }
    ]
}

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(lldb) Launch SDL2",
            "type": "cppdbg",
            "request": "launch",
            "program": "${fileDirname}/${fileBasenameNoExtension}",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "environment": [
                {
                    "name": "DYLD_LIBRARY_PATH",
                    "value": "/opt/homebrew/lib"
                }
            ],
            "externalConsole": true,
            "MIMode": "lldb"
        }
    ]
}

tasks.json

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build with SDL2",
            "type": "shell",
            "command": "/bin/zsh",
            "args": [
                "-c",
                "clang++ -std=gnu++20 -Wall -Wextra -Wpedantic -g \"${file}\" $(sdl2-config --cflags --libs) -o \"${fileDirname}/${fileBasenameNoExtension}\""
            ],
            "options": {
                "cwd": "${fileDirname}"
            },
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": false
            }
        },
        {
            "type": "cppbuild",
            "label": "C/C++: clang++ build active file",
            "command": "/usr/bin/clang++",
            "args": [
                "-fcolor-diagnostics",
                "-fansi-escape-codes",
                "-g",
                "${file}",
                "-o",
                "${fileDirname}/${fileBasenameNoExtension}"
            ],
            "options": {
                "cwd": "${fileDirname}"
            },
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "detail": "Task generated by Debugger."
        }
    ]
}

and the test script I was using(with the error in the include):

#include 
#include 

int main() {
    if (SDL_Init(SDL_INIT_VIDEO) != 0) {
        std::cerr << "SDL_Init Error: " << SDL_GetError() << "\n";
        return 1;
    }
    SDL_Quit();
    std::cout << "SDL2 initialized successfully\n";
    return 0;
}

SDL2 was installed with homebrew and it should be in it's usual path for MacOS.

c++ macos visual-studio-code sdl-2