How to invoke SDL2_image on SteamDeck apps?

Hi Folks,

I had recently added onto an older post about SDL2_image from a different OP with some questions, that were responded to by @icculus and a few others with helpful information, but it appears that since then that the original message thread by the OP was removed entirely. My links back to the post no longer work. I hope it’s ok to start a new post here. In any event, I’m still trying to get an app that uses SDL2_image to run on the SteamDeck and not sure if I’m approaching it correctly.

At the advice of helpful folks on this forum, I was pointed toward the Steam Runtime Environment where I learned about ‘scout’ and ‘soldier’ versions and a docker image available to pull that includes the ‘scout’ Steam Runtime Environment: GitHub - ValveSoftware/steam-runtime: A runtime environment for Steam applications.

On my dev pc which runs Manjaro Linux, I installed docker, then ran the virtual image as a container. To my surprise, the docker container (which includes the Steam Runtime Environment for ‘scout’) has SDL2_image shared object files located in /usr/lib/x86_64-linux-gnu along with all the other SDL2 .so files. Further, I can compile and link my app inside the scout container with no issues (using clang++). I can even run that file in the container (though no SDL window actually materializes – I assume this is a docker limitation?).

Now when I copy the executable out of the container and into SteamOS on my SteamDeck, I pull up a Konsole prompt and go to run the file compiled in my scout container. It gives me an error:

./game: error while loading shared libraries: cannot open shared object file: No such file or directory.

It would appear that SDL2_image shared objects are located on the Steam Runtime Environment container (scout), but aren’t included on the SteamOS on steam deck itself. Has anyone here successfully implemented an SDL2 app that uses SDL2_image (or SDL2_mixer for that matter) and tested it on a steam deck? If so, do you mind describing how did it? I’m beginning to wonder if perhaps I need to add the app as a non-steam game to Steam itself and then try to run it through steam?


So when you launch a game from Steam, it takes some effort to override and enhance system libraries with what it calls the “Steam Runtime,” which is meant to be isolated from the operating system itself, which can be any reasonable Linux system and not SteamOS specifically. The Steam Client includes and manages the Steam Runtime, not SteamOS.

The default SteamOS install doesn’t have SDL_image because the set of apps the OS itself intends to run doesn’t need it, but games launched from Steam might.

When I need to force something to use the Steam Runtime on my Ubuntu system, I don’t add it to Steam–which is a valid approach, too–I use this script (or this one for 32-bit apps).

steamapp64 ./mygame --some-argument

This also gets you the Steam Overlay, even though you didn’t launch from the Steam Client.

(I don’t know if this is the best way to do this, but this all works for me.)

Thanks @icculus your your replies. And thanks for providing the script. If it’s helpful, here is a link to my git repo that represents an absolute bare bones project that is attempting to cross-compile Wind32 and Linux, and eventually be deployed on the steam deck. It does nothing other than initialize the 1200x800 steamdeck resolution in full screen, then it renders the color red on the screen and waits for either a gamepad button to be pressed, or the ESC key to be pressed to break the gameloop and end the app. I included SDL2_image.h only because I know eventually I’ll want to use it later on to load .PNGs. If you happen to have a few moments to peek at my src/main.cpp and src/core/Game_Loop.cpp to let me know if I’m approaching this incorrectly, I’d greatly appreciate it.

I tried a few things below… Each of the steps below I did after compiling/building my app FROM WITHIN the Valve Steam Runtime Environment docker container that I pulled:
sudo docker pull sudo docker run -it
Then I docker cp copied my repo folder in, and ran the make file “make release” to build the game executable file in BrickBreaker/build/linux folder.

  1. Running ./game from inside the docker container pulled from sudo docker pull (the Scout Steam Runtime Environment). By adding cout statements in various places, I was able to determine that from within the scout docker container, no SDL input events are ever detected. Additionally, the fullscreen is never initialized to the color red, and it appears that the PresentRenderer() function is skipped in the game loop. Is this something to be expected when running SDL apps inside Docker containers?

  2. I tried using your SteamApp64 script to run the game executable after I copied it back out of the docker container after compiling. Here is the output I got:

  3. Finally, I tried copying the executable over to my steam deck, and from SteamOS, I added the game to Steam Client as a Non Steam Game and tried to execute it from there. I couldn’t really tell what if anything it did. The Play icon in Steam overlay changed to “Stop” and then immediately changed back to “Play” again as if nothing had occurred. The same behavior occurred on my Dev machine in Manjaro using the Steam Client there, adding the game executable as a non steam game. Except this time the screen flashed once (likely attempting to change resolution to 1200x800?) before stopping.

I think that’s everything for now. If this is starting to stretch the scope of the SDL forum and getting more into something that I might want to ask in a Valve discussion board related to deploying games on steamdeck, please let me know - I can certainly see if they have any ideas… I may anyway.


If you’re only loading images that you control there’s always stb_image, which is a single-file, header-only image loader that can do PNG, JPG, and a couple others. AFAIK it’s what SDL_image uses under the hood to load PNGs now anyway.

If you’re only loading images that you control there’s always stb_image , which is a single-file, header-only image loader that can do PNG, JPG, and a couple others.

Looks like a good opportunity to advertise my header-only SDL_image-like library that uses stb_image.h:

1 Like

Thanks everyone for your replies. I think that perhaps I am beginning to understand that the issue I think I’m having with SDL2_image may actually a more global SDL or even C++ issue with how to deploy something that uses SDL onto Steam within a Steam Deck. @icculus tipped me off with the comment about how running in SteamOS isn’t the same as running in Steam and the libraries that come with SteamOS are somewhat irrelevant because the Steam Runtime Environment should provide the necessary libraries to run C++/SDL apps.

I originally opened this post thinking my issue was related to Steam Deck not having SDL2_image. This turns out to be not true - in that while SDL2_image may not be included in the SteamOS image, it IS part of the Steam Runtime Environment ‘scout’. Other SDL add-ons including SDL_mixer are also included in the Runtime environment. So for the scope of this post, I think that is a closed issue. Additionally, it turns out, I didn’t need to statically link anything, hen building the app, even the libstdc++. Those appear to get picked up through the Runtime Environment when running in Steam.

I still don’t have a working executable on the steam deck that produces the red screen I’m expecting and responds to the ESC key to exit the game loop, but I was able to see that happen on my Manjaro Linux Dev pc with Steam when I ran the game through steam…

So I think I’m getting closer. Again, I’ll post about that in another thread to figure out what are possibly more basic things I’m doing incorrectly to run an SDL app on Steam Deck (within Steam). I found some good content on the website about building an SDL app for Steam Deck. I want to make sure I’ve exhausted that documentation before posting a new thread, if I can’t figure it out on my own.


Hi Folks,

After looking through things a bit more, reading up on the SDL site for installation/usage of SDL on Steam, I believe that this initial question in this thread still stands to understand how folks are using SDL2_image on apps that run under Steam Runtime Environment (scout). I’m posting a link (BrickBreaker/build/linux at 5bc2be2e8a5e9dc742c58da6d7feb4af08b0f20a · DaveGuenther/BrickBreaker · GitHub) to a specific commit on my project where I have 4 executable files (all variations of the simple sdl app that turns the screen red and waits for an ESC key press) in the folder:

  • game - This was built in my up-to-date manjaro dev pc (newest versions of clang++, SDL), but I did NOT link in SDL2_image (no linker flag -lSDL2_image)
  • game-sdl2-image - This was built in the same up-to-date Manjaro linux, however I added in the SD2_image option (linker flag -lSDL2_image)
  • game-steamrt - This was built using the Valve provided docker container for Steam Runtime Environment (Scout) using the link in the above post. It did NOT have SDL2_image linked in (no linker flag -lSDL2_image).
  • game-steamrt-sdl-image - This was built using the Valve provided docker container for Steam Runtime Environment (scout). It DID include the SDL2_image linked in (linker flag -lSDL2_image)

I brought these four files over to the steam deck and added them each as non-steam games. Actually, for this I use the following command to generate an error log that I’ve provided to this post at the bottom.

steam 2>&1 | tee ~/steam_error.log

This game me access to the steam overlay where I could test each app. Here are the results:

  • game - Succeeded - See log lines 204-221
  • game-sdl2-image - Failed - See log line 255 /home/deck/BrickBreaker/build/linux/game-sdl2-image: error while loading shared libraries: cannot open shared object file: No such file or directory
  • game-steamrt - Succeeded See log lines 295-315
  • game-steamrt-sdl2_image - Failed See log line 182 /home/deck/BrickBreaker/build/linux/game-sdl2-image: error while loading shared libraries: cannot open shared object file: No such file or directory

So, based on the test results, it appears that I can build SDL apps either using my current version of clang++ and SDL or the versions included in the Steam Runtime Environment Docker (Scout), and they will work on the steam deck. However, any attempts to invoke SDL2_image in my app are met with .so file not found errors when run within steam on the steamdeck. I’ve attached my log file for reference…

steam_error.log (23.8 KB)

Here is the peculiar part though. I went into the steam-runtime directory, and used their file to run one of my SDL2_image apps, which is supposed to ensure that the app is invoked within the Steam Runtime Environment (Scout), and it appears to work this way:

So I suppose I have a new question for the community. Based on what you see here, do you think that perhaps my Steam Runtime Environment may not be working on Steam on my steam deck when I try to run these games from within Steam? Could it instead be defaulting only to the SDL2 shared object files that comes with SteamOS and not the SDL2 (and SD2_image shared objects) that come with the Steam Runtime Environment? Is there anything else you see going on here that might help be get applications that want to use the companion add-ons to SDL to work on the steam deck? I have though about creating a run script in my linux directory that overloads the LD_LIBRARY_PATH to hit that game directory first and then copying all the .so files and their dependencies there, but from what I’ve read on the SDL forum and other places, that approach seems counter productive to the Steam Runtime Environment.


Thanks for this, Daniel. I tried out your library and it works very well. I’ve got the SDL logo showing up on an app when running through the Steam Deck! I appreciate your help with this.