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.