Apr 16,
2020

Change Icons on Gnome Programmatically

Howdie Interweb surfer!

I recently discovered you can change folder icons in Gnome programmatically using gio. I was organizing my home directory and wanted to color-code folders visually - doing this through the GUI works for one folder, but 10 folders? Time to script it.

Setting a Custom Icon

To set a custom icon for a folder or file:

gio set -t string '/path/to/folder' 'metadata::custom-icon' 'file:///path/to/icon.svg'

Note the file:// URI prefix is required. Icons are typically in SVG format. Icons can be found in:

  • ~/.local/share/icons/ (user-installed themes)
  • /usr/share/icons/ (system themes)
  • /usr/share/pixmaps/ (legacy location)

Example with an existing system icon:

gio set -t string ~/projects/blog 'metadata::custom-icon' \
  'file:///usr/share/icons/gnome/scalable/places/folder-documents.svg'

Checking Current Icon

To see what icon is currently set:

gio get '/path/to/folder' 'metadata::custom-icon'

Removing a Custom Icon

To revert to the default icon:

gio set -t unset '/path/to/folder' 'metadata::custom-icon'

Remove custom icons from multiple folders:

for dir in ~/projects/*; do
  gio set -t unset "$dir" 'metadata::custom-icon'
done

Batch Operations

Here's how I solved my 10-folder problem. Simple approach - apply the same icon to all folders:

for dir in ~/projects/*; do
  gio set -t string "$dir" 'metadata::custom-icon' \
    'file:///usr/share/icons/gnome/scalable/places/folder-visiting.svg'
done

For more control, color-code different project types. My icon theme has 14 color folder variants:

  • Red, blue, green, yellow, orange, pink
  • Purple, violet, magenta, cyan
  • Brown, grey, black, white

Use a variable to avoid repetition. Replace your-theme with your icon theme name - check ls ~/.local/share/icons/ or ls /usr/share/icons/ to find installed themes:

ICON_BASE="file:///usr/share/icons/your-theme/scalable/places"

# Active projects = green
for dir in ~/projects/active-*; do
  gio set -t string "$dir" 'metadata::custom-icon' "$ICON_BASE/folder-green.svg"
done

# Archived projects = grey
for dir in ~/projects/archived-*; do
  gio set -t string "$dir" 'metadata::custom-icon' "$ICON_BASE/folder-grey.svg"
done

# Important projects = red
for dir in ~/projects/urgent-*; do
  gio set -t string "$dir" 'metadata::custom-icon' "$ICON_BASE/folder-red.svg"
done

Troubleshooting

If the icon doesn't update: - Refresh the file manager (F5 in nautilus) - Verify the icon file exists and path uses file:// prefix - Check file permissions on the target folder - Works on Gnome 3.x+ with nautilus/files - Note: Icon metadata may not persist on network mounts, NTFS, or FAT filesystems - only tried on ext4

Color-coding 10 folders takes under 10 seconds. Much better than clicking through the GUI.

gnome