XDG-ICON-RESOURCE(1)

📦
version 1.2.1 · 14 versions
, in arch rolling, ubuntu resolute, ubuntu stonking

💅 XDG-ICON-RESOURCE(1)

okay so bestie, welcome to the xdg-icon-resource manual page — it's part of the xdg-icon-resource Manual, and honestly? it's giving underrated icon-management royalty. 👑

✨ NAME ✨

xdg-icon-resource — the command line tool for (un)installing icon resources. that's it. that's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

okay so here's literally every way you can call her. copy these exactly, no cap:

xdg-icon-resource install [--noupdate] [--novendor] [--theme theme]
                  [--context context] [--mode mode] --size size
                  icon-file [icon-name]
xdg-icon-resource uninstall [--noupdate] [--theme theme]
                  [--context context] [--mode mode] --size size
                  icon-name
xdg-icon-resource forceupdate [--theme theme] [--mode mode]
xdg-icon-resource {--help | --manual | --version}

🦋 DESCRIPTION 🦋

so like, the xdg-icon-resource program is your girl for installing icon resources into the desktop icon system — so your menu entries look cute, your desktop icons actually show up, and your file types get a little graphic representation. main character energy for your pixels fr fr. ✨

the desktop icon system finds icons by name, not by "vibes." depending on the size you need, the icon theme you picked, and the context the icon lives in, it goes hunting for the right icon resource to depict that icon. and icon resources can be XPM files or PNG files. that's the whole menu. 💖

and just so you know she's legit: the desktop icon system works according to the XDG Icon Theme Specification at http://www.freedesktop.org/wiki/Specifications/icon-theme-spec — you know, the icon theme spec. iykyk. 🧚

👑 COMMANDS 👑

  • install — installs the icon file indicated by icon-file into the desktop icon system under the name icon-name. real talk: icon names do not have an extension. if you don't hand over icon-name, the name gets derived from icon-file. the icon file must have .png or .xpm as its extension. and oh? 👀 if a matching .icon file exists in the same location as icon-file, it gets installed too. bonus content, we love to see it.
  • uninstall — removes the icon indicated by icon-name from the desktop icon system. heads up bestie: icon names do not have an extension. don't add one. i'm serious. 🙈
  • forceupdate — forces an update of the desktop icon system. this is only useful if the last call to xdg-icon-resource included the --noupdate option. so basically: you told her "hold that thought," and now you're telling her "okay go." 💅

🔥 OPTIONS 🔥

  • --noupdate — postpones updating the desktop icon system. if you're adding a bunch of icons one after another, this flag says "more changes are coming, you don't gotta refresh the whole desktop icon system right this second." patience, queen. 🫶
  • --novendor — normally xdg-icon-resource checks to make sure an icon file going into the apps context has a proper vendor prefix. this option turns that check off.

so what even is a vendor prefix? it's alpha characters ([a-zA-Z]) terminated with a dash ("-"). companies and organizations are encouraged to use a word or phrase — preferably the organization's name, something they hold a trademark on — as their vendor prefix. and the whole point? preventing name conflicts. so nobody's icon gets confused with anybody else's. ✨

  • --theme theme — installs or removes the icon file as part of theme. if you don't specify a theme, the icons get installed as part of the default hicolor theme. applications may install icons under multiple themes, but they should at least install icons for the default hicolor theme. like, minimum effort bestie. do the bare minimum and it's this. 💖
  • --context context — specifies the context for the icon. icons used in the application menu and as desktop icons should use apps as the context — and that's the default context. icons used as file icons should use mimetypes as the context. other common contexts are actions, devices, emblems, filesystems and stock. pick your lane, slay. 🌈
  • --size size — specifies the size of the icon. all icons must be square. periodt. common sizes for icons in the apps context are: 16, 22, 32, 48, 64 and 128. common sizes for icons in the mimetypes context are: 16, 22, 32, 48, 64 and 128. (yes, same list. iconic of them honestly.) ⭐
  • --mode mode — mode can be user or system. in user mode the file is (un)installed for the current user only. in system mode the file is (un)installed for all users on the system. usually only root is allowed to install in system mode. 👀

the default is to use system mode when called by root, and to use user mode when called by a non-root user.

  • --help — show command synopsis. quick lil cheat sheet. 📋
  • --manual — show this manual page. hi, you are here. 🎀
  • --version — show the xdg-utils version information. 💜

🌟 ENVIRONMENT VARIABLES 🌟

xdg-icon-resource honours the following environment variables — she's polite like that:

  • XDG_UTILS_DEBUG_LEVEL — setting this environment variable to a non-zero numerical value makes xdg-icon-resource do more verbose reporting on stderr. setting a higher value increases the verbosity. so if you're nosy (same), crank it up. 🔍
  • XDG_UTILS_INSTALL_MODE — this environment variable can be used by the user or administrator to override the installation mode. valid values are user and system. you're in charge now. 👑

💀 EXIT CODES 💀

an exit code of 0 indicates success, while a non-zero exit code indicates failure. the following failure codes can be returned:

  1. 1 — error in command line syntax.
  2. 2 — one of the files passed on the command line did not exist.
  3. 3 — a required tool could not be found.
  4. 4 — the action failed.
  5. 5 — no permission to read one of the files passed on the command line.

🌈 SEE ALSO 🌈

xdg-desktop-icon(1), xdg-desktop-menu(1), xdg-mime(1), Icon theme specification[1]

🍓 EXAMPLES 🍓

okay so real scenarios, bestie. here's how you'd actually use her.

to install an icon resource to depict a launcher for the application myfoobar, the company ShinyThings Inc. can use:

xdg-icon-resource install --size 64 shinythings-myfoobar.png

to install an icon for a new application/x-foobar file type one can use:

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

this will install two icons with the name application-x-foobar but with different sizes. and that's how it's done. 💅✨

💖 AUTHORS 💖

  • Kevin Krammer — Author.
  • Jeremy White — Author.

Copyright © 2006

📝 NOTES 📝

  1. Icon theme specification — http://www.freedesktop.org/wiki/Specifications/icon-theme-spec/
and that's the whole page bestie!! remember: every flag, every default, every exit code — keep it in your brain. no cap. 🫶

and before you go — this whole thing comes from xdg-utils 1.0, dated 12/06/2025. that's the version and the date, so you know exactly what era this icon-slinging queen is from. 🌸💖 go install some icons, you got this. ✨

📦 where this page comes from