Add a custom Ubuntu icon for an app that does not have one: create a .desktop file in ~/.local/share/applications/ with the Icon= key pointing at a PNG, then refresh the icon cache. The right path for user-installed apps is ~/.local/share/applications/. The right path for system-wide apps is /usr/share/applications/. The team that has the right .desktop file has a working app launcher icon.
Table of contents
- The .desktop file format
- Making the icon visible
- Where to put the icon file
- System-wide vs user-specific
- FAQ
The .desktop file format
The right way to add a custom icon for an app on Ubuntu is a .desktop file. The minimum fields are Name, Exec, Icon, and Type=Application:
[Desktop Entry]
Version=1.0
Name=My App
Comment=My custom application
Exec=/usr/local/bin/myapp
Icon=/home/alice/.local/share/icons/myapp.png
Terminal=false
Type=Application
Categories=Utility;Save this as ~/.local/share/applications/myapp.desktop.
Making the icon visible
After saving the file, the right answer is to refresh the icon cache:
sudo update-desktop-database ~/.local/share/applications/
sudo gtk-update-icon-cache -f -t ~/.local/share/icons/Or just log out and back in. The right answer is that the icon will appear in the Activities overview and the launcher.
Where to put the icon file
The right answer is to put the PNG in ~/.local/share/icons/ (for user-specific) or /usr/share/pixmaps/ (for system-wide). The Icon= key in the .desktop file points at the absolute path or a name without the extension that is searched in the standard icon directories.
System-wide vs user-specific
The right answer for a user-specific app is ~/.local/share/applications/. The right answer for a system-wide app (one that all users should see) is /usr/share/applications/. The right answer is to use the user-specific path unless you are installing for all users.
FAQ
Where can I get app icons?
The right answer for a free app is the developer’s website or the project’s GitHub. The right answer for an icon pack is a free icon set like Papirus or Numix. The wrong answer is to use a copyrighted icon.
What is the right icon size?
The right answer is 512x512 PNG. Modern desktop environments support 16x16 to 512x512 in the same file (the .desktop file can reference a scalable SVG, but PNG is more compatible).
Why does the icon not show up?
The right answer is to log out and back in, or to run gtk-update-icon-cache. The wrong answer is to keep restarting the desktop.
What is the difference between .desktop and .directory?
.desktop is for application launchers. .directory is for folder categories in file managers. The right answer is to use .desktop for app icons.
Can I use an SVG icon?
Yes. Put the SVG in ~/.local/share/icons/ and reference it in the Icon= key. The right answer is to also include a PNG fallback in case the desktop environment does not render SVG.
My icon is too small. How do I fix it?
The right answer is to use a larger source PNG. The wrong answer is to scale up a small PNG, which produces a blurry result.
What is the Categories key?
It tells the launcher which category the app belongs to (Utility, Development, Network, etc.). The right answer is to set it to a relevant category. The wrong answer is to leave it empty, which puts the app in the wrong category.
If you are sizing the infrastructure for the kind of project this post covers, the RunxBuild hosting calculator is the right place to model the line items. The compute, the memory, the storage, the bandwidth, the database - each one is a separate number, and the team’s mental model for the platform is the sum of those numbers. The RunxBuild dashboard is where the team sees the actual usage in one place.
Useful related references: