Custom Mime Icons in Gnome

Changing the icon GNOME shows for a specific file type — say, giving .md files their own icon instead of a generic text-file icon — doesn't require touching the system's Adwaita theme or any application icons. GNOME's icon-theme inheritance model makes it possible to override exactly one MIME icon safely.

The Core Idea

Instead of modifying hicolor or a system theme directly, create a small custom icon theme that inherits from the current system theme (usually Adwaita) and overrides only the one MIME icon needed. GNOME automatically falls back to the parent theme for everything else, so application icons, Wine icons, and web-app icons (Brave, Chrome, etc.) are never affected.

Theme Directory Structure

~/.local/share/icons/<theme-name>/
├── index.theme
└── <size>/<context>/
    └── <mime-icon-name>.png

Where <size> is something like 128x128, <context> is mimetypes, and <mime-icon-name> is the icon name for that MIME type.

index.theme Template

[Icon Theme]
Name=Custom MIME Icons
Comment=User-level MIME icon overrides
Inherits=Adwaita
Directories=128x128/mimetypes

[128x128/mimetypes]
Size=128
Type=Fixed
Context=MimeTypes

GNOME resolves icons by checking the active theme first; if the icon isn't found there, it falls back to whatever Inherits= points at — which is what keeps this approach safe.

Worked Example: a Custom .md Icon

Identify the MIME type:

xdg-mime query filetype README.md
# text/markdown  →  icon name: text-markdown

Create the theme directory:

mkdir -p ~/.local/share/icons/md-custom/128x128/mimetypes

Create index.theme:

nano ~/.local/share/icons/md-custom/index.theme

[Icon Theme]
Name=Markdown Custom
Comment=Markdown icon override
Inherits=Adwaita
Directories=128x128/mimetypes

[128x128/mimetypes]
Size=128
Type=Fixed
Context=MimeTypes

Add the icon file, named after the MIME icon name:

cp markdown.png ~/.local/share/icons/md-custom/128x128/mimetypes/text-markdown.png

Activate the theme:

gsettings set org.gnome.desktop.interface icon-theme 'md-custom'
nautilus -q && nautilus &   # restart Files to pick it up

.md files now use the custom icon; every other file type, and all application icons, stay exactly as they were.

Extending to Other File Types

Reverting

gsettings set org.gnome.desktop.interface icon-theme 'Adwaita'

What not to do: don't modify hicolor directly, don't rename a PNG to a .svg extension expecting it to work, and don't change the system-wide icon theme instead of layering a user-level one.