Demystifying StartupWMClass :: Terminal ThoughtsDemystifying StartupWMClass<br>2026-06-23<br>:: quest<br>:: 7 min read (1480 words)<br>#code<br>#linux<br>Eventually, every Linux user opens an app and finds a generic placeholder icon staring back from their dock/panel. It looks like the dock is broken, but it almost never is - the cause is a single line in the app’s .desktop file, and it only takes a minute to fix. Here’s how to find it and fix it yourself, on any desktop.<br>Anatomy of a Desktop File⌗<br>Every app you launch from a menu, dock, or panel is backed by a .desktop file: a small text file telling your system what to run, what to call it, and which icon to show. These live in /usr/share/applications/ for system-wide apps, and ~/.local/share/applications/ for your own. Let’s look at a real one, the file that ships with Tor Browser.<br>[Desktop Entry]<br>Version=1.0<br>Type=Application<br>Name=Tor Browser<br>Exec=tor-browser %u<br>Icon=tor-browser<br>Categories=Network;WebBrowser;Security;<br>MimeType=text/html;text/xml;application/xhtml+xml;x-scheme-handler/http;x-scheme-handler/https;application/x-xpinstall;application/pdf;application/json;<br>Comment=Anonymous browsing using Firefox and Tor<br>StartupWMClass=tor-browser
Each line is a key=value pair from the freedesktop Desktop Entry Specification. The ones worth knowing:<br>[Desktop Entry]: the header every desktop file starts with.<br>Version: the version of the Desktop Entry Specification the file follows, not the app’s own version (a frequent mix-up).<br>Type: the kind of entry; Application means it launches a program.<br>Name: the label shown in menus, docks, and panels.<br>Exec: the command to run; %u gets replaced with a URL when you open one.<br>Icon: the icon to display, either a name looked up in your icon theme or an absolute path to an icon file.<br>Categories: the menu sections the app shows up under.<br>MimeType: the file types and link schemes it can open.<br>Comment: the tooltip text.<br>StartupWMClass: the field this whole post is about. More on it next.<br>What is StartupWMClass?⌗<br>Open an app and a window appears, but how does your dock know which launcher it belongs to? It needs to pair the two, so the window groups under the right icon instead of showing the generic placeholder from earlier. StartupWMClass is one of the hints that makes that pairing work. As the spec puts it, a desktop file with this key is known to “map at least one window with the given string as its WM class or WM name hint.” In plain terms: it tells your dock what the app’s window will call itself, so the two can be matched.<br>Here’s the important part: StartupWMClass is only one of those hints. For example, Plank Reloaded matches windows to launchers using BAMF, which also looks at the application identifier and the binary name. If an app’s window already lines up with its launcher through either of those, the dock can find the right icon on its own, and StartupWMClass isn’t needed at all. That’s also why a wrong value is worse than none: a bad StartupWMClass overrides the signals that would have worked, pointing the dock at a window class that never appears.<br>This also explains why a broken icon sometimes looks low-quality rather than missing. A matched window uses the crisp icon from the file’s Icon entry; an unmatched one falls back to the icon the app embedded in its window, often low-resolution. Same cause, subtler symptom.<br>Finding the WM_CLASS⌗<br>To set StartupWMClass correctly, or to confirm an existing value is wrong, you need to know what the window actually calls itself. That identity is its WM_CLASS (or, on Wayland, its app_id). It’s case-sensitive and often isn’t the name you’d guess, so it’s worth reading the real value rather than assuming. How you do that depends on your setup, so here’s the approach for X11, Wayland, and KDE.<br>X11⌗<br>On X11, the classic tool is xprop. Open the app with the broken icon, run this in a terminal, and your cursor turns into crosshairs:<br>xprop WM_CLASS
Click the application’s window and it prints the value. For Tor Browser:<br>WM_CLASS(STRING) = "Navigator", "Tor Browser"
There are two strings: the instance name first, the class second. Either can serve as a StartupWMClass, but the more specific one is the safer choice. Here, Navigator is the generic name that Firefox-based browsers share, while Tor Browser is unique to this app. Notice that neither string is tor-browser, the value the file actually ships with. That mismatch is a bug, and we’ll fix it shortly.<br>Wayland⌗<br>Wayland is stricter than X11: for security, applications can’t freely inspect each other’s windows, so xprop only works for apps running through XWayland. Native Wayland apps don’t expose a WM_CLASS at all. Instead they set an app_id, and that’s the value your desktop matches against.<br>On GNOME, the easiest way to read it is the built-in Looking Glass debugger. Press Alt + F2, type lg, and hit Enter, then...