[Guide] Create a desktop icon for custom app or command

In this guide I will explain you how to create a desktop icon for a custom command or application.

As example, I will use a Java game Shattered Pixel Dungeon that I showed how to run in one of my previous guides ([Guide] Run java executables on the JingPad A1 (Shattered Pixel Dungeon)).

To create a desktop icon you will have to create a .desktop file that follows the XDG Desktop Entry specification.

Before starting, you have to install the desktop-file-utils package that will help you to create and validate your .desktop file:

sudo apt install desktop-file-utils

Now create with your favorite editor the file that will represent your desktop entry, it must end with the “.desktop” file extension.
For Shattered Pixel Dungeon I created the file “com.shatteredpixel.shatteredpixeldungeon.desktop” but you can name yours as you want.

In this file you will have to put this:

[Desktop Entry]
Name=Shattered Pixel Dungeon
Comment=Traditional roguelike game with pixel-art graphics and simple interface
Exec=java -jar ShatteredPD-v1.0.3-Desktop.jar

You can change the name and comment to fit your application.
You should leave the type entry to Application.

Now you have to replace the content of the Exec, Path and Icon entries.

Exec is the command that is run when you will touch the icon. Because ShatteredPD-v1.0.3-Desktop.jar is in a folder that is in my PATH environment variable, I can skip the absolute path, if it is not your case, you must use an absolute path.
If you want to run a terminal app/command, you should add the following line in the file:


The path entry set the folder in which the program will be executed.

And last but not the least, the Icon entry allow to choose which icon will be used to represent your command/application on your home screen.

In my case, the Shattered Pixel Dungeon java executable has it’s icon embeded. As .jar executables are just zip archives, I duplicated the file, renamed the second to add the “.zip” file extension and then extracted the content. I found the icon that I want inside the icon subfolder of the extracted archive, then pasted it to a convenient location.
But you can use whatever image you want as long as it is a PNG or SVG.

When the content of your .desktop file seems ok for you, you can save it and run the following command to validate it.

desktop-file-validate YOUR_FILE.desktop
If your file is valid, the command should return nothing. Else it will explain why not.

Once your file is valid, this command will install and put your file in the right directory:

desktop-file-install --dir=/usr/share/applications PATH_TO_YOUR_FILE.desktop

If everything worked fine the icon should appear on your home screen.
If the icon is blank, check that the icon path and name are good.


I hope this guide helped you.

1 Like