Install Linux Icons Safely with xdg-icon-resource

You will install a PNG or XPM icon into an XDG icon theme, check where it landed, and remove it again without guessing which user's desktop you changed. The examples use xdg-icon-resource 1.1.3 from xdg-utils 1.1.3-4.1ubuntu3, installed on this machine.

Allow about ten minutes. You need an icon file ending in .png or .xpm, a shell, and a desktop using the XDG icon theme layout. User-mode installation needs no elevated privileges. System mode changes the shared desktop resources and normally needs root.

1. Check the command and the input

Confirm which executable is being used, then check the source file before changing the icon theme:

$ command -v xdg-icon-resource
/usr/bin/xdg-icon-resource
$ xdg-icon-resource --version
xdg-icon-resource 1.1.3
$ file /path/to/shinythings-myapp.png
/path/to/shinythings-myapp.png: PNG image data, 64 x 64, ...

The command accepts PNG and XPM files only. The image must be square, and --size describes the icon's theme size, such as 64, not a request for the command to resize the image. Do not rely on a misleading filename: inspect the file if the dimensions matter.

2. Install an application icon for your user

Use the apps context for a launcher or desktop application icon. Choose a name with a vendor prefix and omit the file extension from the icon name. This command defaults to the hicolor theme:

$ xdg-icon-resource install --mode user --context apps --size 64 \
    /path/to/shinythings-myapp.png shinythings-myapp

There is normally no success message. The command copies the icon under the user's data directory, usually below $XDG_DATA_HOME/icons/hicolor/64x64/apps/, or below ~/.local/share/icons/ when XDG_DATA_HOME is unset. If a file with the same icon name already exists at that size, this replaces it.

For an apps icon, the default vendor check expects the name to start with alphabetic characters followed by a dash. shinythings-myapp passes that rule. If you deliberately need a name without a vendor prefix, --novendor disables the check, but it also makes name collisions more likely. Prefer a name you control instead.

Verify the copied resource without depending on a desktop menu refresh:

$ test -f "$HOME/.local/share/icons/hicolor/64x64/apps/shinythings-myapp.png" \
    && echo 'icon installed for this user'
icon installed for this user

If you set XDG_DATA_HOME, substitute that directory for $HOME/.local/share. A per-user command must be checked as the same user who will use the icon.

3. Add several sizes or a file-type icon

Install each size separately with the same icon name. The desktop can then select the closest available resource:

$ xdg-icon-resource install --mode user --context apps --size 48 \
    ./shinythings-myapp-48.png shinythings-myapp
$ xdg-icon-resource install --mode user --context apps --size 64 \
    ./shinythings-myapp-64.png shinythings-myapp

For a file type, use the mimetypes context and an icon name such as application-x-foobar:

$ xdg-icon-resource install --mode user --context mimetypes --size 48 \
    ./mime-foobar-48.png application-x-foobar
$ xdg-icon-resource install --mode user --context mimetypes --size 64 \
    ./mime-foobar-64.png application-x-foobar

Other documented contexts include actions, devices, emblems, filesystems and stock. The context is part of the destination path, so using apps when you meant mimetypes can look like a missing icon rather than an installation error.

4. Batch changes without repeated cache updates

When adding several resources, pass --noupdate to each install and refresh once at the end:

$ xdg-icon-resource install --mode user --noupdate --context apps --size 48 \
    ./shinythings-myapp-48.png shinythings-myapp
$ xdg-icon-resource install --mode user --noupdate --context apps --size 64 \
    ./shinythings-myapp-64.png shinythings-myapp
$ xdg-icon-resource forceupdate --mode user --theme hicolor

forceupdate is useful after deferred updates. It does not install an icon and cannot repair a wrong name, context or size. If the icon is still absent, inspect the destination and check that the desktop is looking at the same user data directories.

5. Use system mode only when you mean all users

System mode writes to a shared icon directory. It is an administrative change, so review the target and use an explicit mode rather than relying on whether the shell happens to be running as root:

$ sudo xdg-icon-resource install --mode system --context apps --size 64 \
    /path/to/shinythings-myapp.png shinythings-myapp

The tool normally selects system mode for root and user mode for a non-root user. XDG_UTILS_INSTALL_MODE can override that selection with user or system. Check the environment before a scripted install:

$ printf 'XDG_UTILS_INSTALL_MODE=%s\n' "${XDG_UTILS_INSTALL_MODE:-unset}"
XDG_UTILS_INSTALL_MODE=unset

Do not add sudo just to make a user icon visible. It can put the resource in the shared tree while you are checking the user's tree, which creates confusing duplicates.

6. Remove an icon and recover from mistakes

Uninstall removes files for the selected name, theme, context, size and mode. It does not ask for confirmation. Record those values from the install command before removing anything:

$ xdg-icon-resource uninstall --mode user --theme hicolor \
    --context apps --size 64 shinythings-myapp
$ test ! -e "$HOME/.local/share/icons/hicolor/64x64/apps/shinythings-myapp.png" \
    && echo 'icon removed'
icon removed

To undo an accidental removal, run the original install command again from the original PNG or XPM file. If you used --noupdate, finish with forceupdate. Keep source files until the desktop has displayed the replacement you intended.

For diagnostics, set XDG_UTILS_DEBUG_LEVEL=1 or a higher non-zero value. The command reports more detail on standard error. Exit status 0 means success; statuses 1 through 5 distinguish syntax, missing files, missing tools, an operation failure and unreadable input. Capture the status immediately if a script needs to act on it.