Running SDL2 libraries on macOS is slightly different than running them on Linux and Windows systems.

You might want to run these libraries to work on a native application or a video game that requires graphics and access to other system controls.

Since there are a few pitfalls to avoid I have put this resource together that covers installing SDL2 and SDL2_image into the system.

Finally, I’ll include a test program to open a window and a command to compile it.
It is written in C but SDL can be used with C++, Rust and a few other languages as well.


The first step is to get all files required into your system.

Download SDL2 by picking the .dmg one from the release list:

Additionally, download the SDL2_image library (also a .dmg from its release list:

Execute the SDL2 file (will be named something similar to SDL2-2.30.4.dmg) and a window will open with a few files and an SDL2.framework folder.

Open Finder, click Go then Go to folder... and type /Library/Frameworks which will open the contents of that folder. Drag SDL2.framework to /Library/Frameworks and repeat the steps for the SDL2_image file.

There should be two additional folders in /Library/Frameworks, SDL2.framework and SDL2_image.framework.

Compile a program

One way to test the installation is to write a program, this one opens a window in the system.

Create a main.c file and add the contents below to it:

#include <stdio.h>
#include <stdbool.h>
#include <SDL.h>
#include <SDL_timer.h>

int main(void)
    // Attempt to initialize graphics and timer system.
        printf("error initializing SDL: %s\n", SDL_GetError());
        return 1;

    SDL_Window* window = SDL_CreateWindow("Hello, SDL2 on macOS 🍎",
                                       640, 480, 0);
    if (!window)
        printf("error creating window: %s\n", SDL_GetError());
        return 1;

    // Keep the window open, in this case SDL_Delay(5000); statement won't work.
    bool running = true;
    while (running)
        SDL_Event e;
        while (SDL_PollEvent(&e) != 0)
            if (e.type == SDL_QUIT)
                running = false;

    // clean up resources before exiting.

On a terminal window, navigate to the same directory of the main.c file and attempt to compile it:

gcc -o open_window main.o `sdl2-config --libs --cflags` -ggdb3 -O0 --std=c99 -Wall -F/Library/Frameworks -framework SDL2 -framework SDL2_image -lm

This could work first try but in my case I’ve hit quite a few issues a few are solved by the way the header files are included and the structure of the compile command which have already been addressed but there’s a few more I found while trying to compile an SDL2 based program.

One of the issues might look like this:

dyld[94016]: Library not loaded: @rpath/SDL2.framework/Versions/A/SDL2
  Referenced from: <BAD3873A-39CC-4033-8C2A-85A0FC365404> /Users/user/Projects/open_window/open_window
  Reason: no LC_RPATH's found
[1]    94016 abort      ./open_window

The way I solved it was by running the following in the terminal before compiling the program:

export DYLD_FRAMEWORK_PATH=/Library/Frameworks

macOS displays a notice saying “SDL2.framework” cannot be opened because the developer cannot be verified

The issue can be addressed by running the executable, e.g. ./open_window then opening the Privacy & Security settings and scroll to Security.

You will see a button to allow the SDL2.framework, click “Allow Anyway”.
Do the same for SDL2_image.framework if it shows up.

The notice should now show an “Open” option, there’s more context in this Github issue:

Opening a window

Assuming the program compiled correctly we can now open a window by executing the program.

On a terminal run ./open_window and an empty should should now show!

Additional Notes

  • A lot of programs will use #include <SDL2/SDL.h> but in this case #include <SDL.h> needs to be used instead when including SDL related header files.