seticon

Cross-platform CLI to change folder icons on Windows, macOS and Linux.

Accepts common image formats and automatically converts them to a multi-size ICO, then applies the icon using the right mechanism for each desktop environment.

✨ Star History

🎖️ Features

• Cross-platform — Windows, macOS, Linux (GNOME and KDE)
• Many input formats — ico, png, jpg, jpeg, bmp, tif, tiff, webp, svg
• Automatic ICO conversion built in (multi-size: 16, 32, 48, 64, 128, 256); png and ico are used as-is
• Overlay mode — lay your image (or text) over a real folder icon, with color variants and zoom
• Reset — restore the default icon of one or more folders with seticon reset <folders...>
• Content-addressed icon cache with deduplication (same image reused, never re-converted)
• No admin / sudo required for the icon change itself
• Detects the OS and applies the correct mechanism automatically:
  • Windows → desktop.ini + attrib +H +S +R
  • macOS → NSWorkspace.setIcon via osascript (Finder)
  • Linux → gio set metadata::custom-icon (GNOME) + .directory (KDE)

📋 Requirements

• Node.js >= 18.17.0
• Windows: works out of the box
• macOS: Finder automation permission (prompted on first run)
• Linux: gio (part of glib2, present by default on most distros)

📦 Installation

# npm
npm i seticon-cli

# yarn
yarn add seticon-cli

# pnpm
pnpm add seticon-cli

Or install it globally to use the seticon command anywhere:

# npm
npm i -g seticon-cli

# yarn
yarn global add seticon-cli

# pnpm
pnpm add -g seticon-cli

⚙️ Usage

# Set a folder icon (any image is auto-converted to ICO)
seticon set -f "./MyFolder" -i "./icon.png"
seticon set -f "./MyFolder" -i "./photo.webp"

# Shorthand: positional arguments, no flags needed
seticon "./MyFolder" "./icon.png"
seticon convert "./image.jpg" "./icon.ico"

# Long options also work
seticon set --folder "Documents" --icon "logo.svg"

# Convert an image to ICO without setting an icon
seticon convert -i "./image.bmp" -o "./icon.ico"

# Pick specific sizes for the ICO output
seticon convert --icon "photo.png" --output "icon.ico" --sizes 16,32,48

# Reset folder(s) back to their default icon (one or more)
seticon reset "./MyFolder"
seticon reset "./A" "./B" "./C"
seticon "./A" "./B" -r

# Show the full manual
seticon --help

# Switch the interface language, remembered for next runs (en, fr)
seticon --lang fr
seticon -l en

🎨 Overlay mode

Instead of using your image directly, lay it over a real folder icon. Add --overlay (-ov):

# Lay an image over your machine's folder icon, then apply it
seticon set -f "./MyFolder" -i "./logo.png" --overlay

# Color the folder and zoom the overlay (short aliases)
seticon set -f "./Dev" -i "js.png" -ov -va blue -ic variant -z 125

# Color it with a preset or a raw hex
seticon set -f "./Photos" -i "cam.png" -ov -va "#e67e22"

# Draw text on the folder instead of an image
seticon set -f "./Work" --text "WORK" --overlay --variant blue
seticon set -f "./Docs" -t "DOCS" -ov -va red -tc "#ffffff"

# Force the macOS look (the only style you can force from any OS)
seticon set -i "logo.svg" -o "icon.ico" --overlay --os mac --variant red

| Option | Alias | Values | Notes | | ------ | ----- | ------ | ----- | | --overlay | -ov | — | Enable overlay mode | | --os | -os | mac | Force the folder style. Only mac is allowed; otherwise the OS is auto-detected | | --variant | -va | mac: variant name · windows/linux: color preset or #hex | Folder color | | --icon-color | -ic | original, variant | Keep image colors or tint to folder | | --text | -t | any short text | Draw text instead of an image | | --text-color | -tc | #hex | Text color (default: the folder color) | | --zoom | -z | 75, 92, 100, 108, 125 | Overlay size |

Overlay accepts either an image (-i) or text (--text), not both.

💡 Overlay mode is inspired by and credits FolderArt by christianvmm, whose folder designs and approach this feature builds upon.

🖼️ Supported formats

| Input format | Behavior | | ------------------------------------- | --------------------- | | png, ico | used as-is | | jpg, jpeg, bmp, tif, tiff, webp, svg | auto-converted to a multi-size ico |

Converted icons are stored once in a content-addressed cache and reused for identical images, so the same picture is never converted twice.

🖥️ How the icon is applied per OS

| OS | Mechanism | | ------- | ------------------------------------------------------------------- | | Windows | desktop.ini (absolute IconResource) + attrib +H +S +R | | macOS | NSWorkspace.setIcon via osascript (Finder permission on 1st run) | | Linux | gio set metadata::custom-icon (GNOME) + .directory file (KDE) |

🤝 Contributing

We welcome contributions of all kinds — bug reports, feature ideas, documentation fixes and pull requests. Please read the contributing guide and follow our code of conduct before getting started.

📜 License

Licensed under MIT License and copyrights reserved.