Creating WSL2 GUI app shortcuts in Windows with WSLg

Microsoft has built a feature into WSLg where it automatically creates shortcuts in Windows for WSL2-based GUI apps. This is fantastic and works seamlessly for most Linux-based GUI apps installed into WSL2 using a distribution package manager (eg. apt). But, what if we want to add our own shortcuts for apps that aren’t automatically added? This article intends to describe that process.

In the WSLg Github repository README, Microsoft says this about how they automatically create shortcuts to Linux-based GUI apps on Windows:

WSLg makes use of a custom RDP virtual channel between the Weston RDP Server and the mstsc RDP Client running on the Windows host. This channel is used by Weston to enumerate all Linux GUI applications (i.e. applications which have a desktop file entry of type gui) along with their launch command line and icon. The open source WSLDVCPlugin processes the list of Linux GUI applications sent over this channel and creates links for them in the Windows start menu.

You’ll notice from the part I highlighted that they are looking for “applications which have a desktop file entry of type gui”. So, what does that mean?

Linux .desktop files

In Linux, the way to define whether an app includes a GUI is by creating a .desktop file that has a property Type=Application. The location of these files probably depends on the Linux distribution you’re using in WSL2. However, a good first place to check would be /usr/share/applications.

If this doesn’t appear to be the correct place for your distro, maybe try this command to locate where other existing .desktop files might be:

find / -path /mnt -prune -false -o -name '*.desktop'

Now that you know where they’re located, all you need to do is create a .desktop file for the app you want.

NOTE: I would recommend creating the .desktop file somewhere else initially and then moving it to /usr/share/applications after you have the icon in place (continue reading for that). If you don’t do it in this order, WSLg will add the shortcut to Windows, but without the app icon.

.desktop file content

Below is an example of a .desktop file created for PhpStorm.

[Desktop Entry]
Name=PhpStorm
Icon=phpstorm
Comment=Lightning-smart PHP IDE
Exec="/home/user/.local/share/JetBrains/Toolbox/apps/PhpStorm/ch-0/211.7036.8/bin/phpstorm.sh" %f
Version=1.0
Type=Application
Categories=Development;IDE;
Terminal=false
StartupNotify=true

Most of the properties are self-explanatory, so I’ll just highlight a couple of them.

Exec

Make sure this points directly to the application you want to run along with any parameters. The path can even be inside the default WSL2 user folder.

There are some helpful variables you can add to the Exec command. Here are some of the common ones.

• %f — A single file name (including the path), even if multiple files are selected. The system reading the desktop entry should recognize that the program in question cannot handle multiple file arguments, and it should should probably spawn and execute multiple copies of a program for each selected file if the program is not able to handle additional file arguments. If files are not on the local file system (i.e. are on HTTP or FTP locations), the files will be copied to the local file system and %f will be expanded to point at the temporary file. Used for programs that do not understand the URL syntax.
• %F — A list of files. Use for apps that can open several local files at once. Each file is passed as a separate argument to the executable program.
• %u — A single URL. Local files may either be passed as file: URLs or as file path.
• %U — A list of URLs. Each URL is passed as a separate argument to the executable program. Local files may either be passed as file: URLs or as file path.

(source: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html)

Icon

The icon property instructs Linux (and WSLg) where the icon should be located for the app. The .desktop file specification expects that this property is not a path, but a “tag” that Linux Desktop Window Managers (eg. Gnome, KDE, XFCE) can use for theming icons.

In most distros, the icon files should be placed under /usr/share/icons in the appropriate folder. The specification states the following for how it locates the appropriate icon for an application:

The lookup is done first in the current theme, and then recursively in each of the current theme’s parents, and finally in the default theme called “hicolor” (implementations may add more default themes before “hicolor”, but “hicolor” must be last). As soon as there is an icon of any size that matches in a theme, the search is stopped.

With that understanding, unless you are planning on theming your icon with the active theme, you should place your icon in the appropriate place under the “hicolor” folder.

If your icon is an SVG file, it should be placed at /usr/share/icons/hicolor/scalable/apps and the file name before the .svg should be exactly what you put in the Icon property in the .desktop file. So, if your Icon property is set to “phpstorm”, the file should be named “phpstorm.svg”.

If your icon file is a PNG, it should be sized appropriately and placed in the corresponding folder.

Just for context, here is an example of how the GIMP icon is placed.

From the specification, it doesn’t appear that you must put an icon in each of these folders. It appears you should only need to put it into one of these folders.

Put it all together

So, if you put all that together, here is what the process would look like. You’ll notice when I move the .desktop file into /usr/share/applications the shortcut is immediately created in Windows.

Bonus

Let’s say you have some shortcuts from WSL2 that you don’t want in Windows. You can easily remove them by moving (or deleting) the corresponding .desktop file out of the /usr/share/applications folder.