How to install SDL2 on macOS

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.

Installation

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

Download SDL2 by picking the .dmg one from the release list:
https://github.com/libsdl-org/SDL/releases

Additionally, download the SDL2_image library (also a .dmg from its release list:
https://github.com/libsdl-org/SDL_image/releases

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.
    if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0)
    {
        printf("error initializing SDL: %s\n", SDL_GetError());
        return 1;
    }

    SDL_Window* window = SDL_CreateWindow("Hello, SDL2 on macOS 🍎",
                                       SDL_WINDOWPOS_CENTERED,
                                       SDL_WINDOWPOS_CENTERED,
                                       640, 480, 0);
    if (!window)
    {
        printf("error creating window: %s\n", SDL_GetError());
        SDL_Quit();
        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;
                break;
            }
        }
     }

    // clean up resources before exiting.
    SDL_DestroyWindow(window);
    SDL_Quit();
}

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:

https://github.com/libsdl-org/SDL/issues/4689#issuecomment-2189963510

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.