Environment tricks for stubborn apps
The handful of variables that rescue an app which will not render, scale or start.
On this page 3 sections
Most apps need none of this. When one misbehaves, these are the levers, and they are the same ones you would use on any Linux machine with software rendering.
Run an app with a variable set from a terminal in the instance:
LIBGL_ALWAYS_SOFTWARE=1 some-appOr, from your Mac, through the msl command:
msl <instance> env LIBGL_ALWAYS_SOFTWARE=1 some-appThe useful ones#
| Variable | What it does | Reach for it when |
|---|---|---|
LIBGL_ALWAYS_SOFTWARE=1 | Forces Mesa's software renderer | An app renders wrongly on the GPU path |
GALLIUM_DRIVER=llvmpipe | Picks the software driver outright | The same, more firmly |
GSK_RENDERER=cairo | GTK4 draws without OpenGL | A GTK4 app shows a blank or black window |
QT_QUICK_BACKEND=software | Qt Quick draws without OpenGL | A Qt app's interface is blank or garbled |
SDL_VIDEODRIVER=x11 | Stops SDL choosing Wayland | An SDL game exits saying it cannot find a display |
SDL_RENDER_DRIVER=software | SDL draws without GL | An SDL game opens a window and draws nothing |
GDK_BACKEND=x11 | Stops GTK choosing Wayland | A GTK app cannot find a display |
QT_QPA_PLATFORM=xcb | The same for Qt | A Qt app cannot find a display |
MSL already sets the first few of these for apps it launches, so an app started from the Applications tab usually has sensible values. These are for when you are running something by hand, or an app needs something unusual.
Older games and LOVE apps#
Older games, and anything built on an old LOVE (love2d) runtime, are the most common thing to need help. They tend to ask for an OpenGL setup that assumes a real graphics card and give up quietly when they do not get it.
In rough order of what to try:
- Run it from a terminal, so you can see what it actually says.
SDL_VIDEODRIVER=x11— many exit immediately without this because they try Wayland first.LIBGL_ALWAYS_SOFTWARE=1— on the CPU path, where OpenGL 4.5 is available.SDL_RENDER_DRIVER=softwareif it opens a window but draws nothing.- If it is packaged as a Flatpak or Snap, try the plain distribution package instead: sandboxed packages bring their own graphics libraries, which is one more thing between the app and mslgd.
Making it stick#
Adding a line to your shell profile in the instance makes a variable apply to everything you start from a shell:
echo 'export LIBGL_ALWAYS_SOFTWARE=1' >> ~/.profileFor a single app, a better place is the app's own .desktop entry, so launching it from the Applications tab gets the same treatment.