Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
Apr 7, 2022
Mar 5, 2018
Apr 7, 2022
Feb 11, 2022
Aug 3, 2015
Apr 7, 2022
Feb 11, 2022
Feb 11, 2022
Apr 7, 2022
Apr 21, 2016
Apr 7, 2022

npm version license


fileicon — introduction

fileicon is a macOS CLI for managing custom icons for files and folders, as a programmatic alternative to interactively using Finder.

fileicon allows assigning a custom icon to any file or folder, using any image file whose format is recognized by the system.

Caveat: Custom icons rely on extended attributes of the macOS filesystems, HFS+ and APFS. Therefore, custom icons are lost when copying files or folders to filesystems that don't support these attributes; for instance, custom icons cannot be stored in a Git repository.

When assigning an image file with fileicon set, a set of icons in several resolutions is created and stored in the resource fork of the target file itself / of a hidden Icon\r file inside the target folder.

The icon with the highest resolution measures 512 x 512 pixels, and the input image is scaled accordingly.
Note that input images that aren't square can result in distorted icons; for best results, provide square images.

Note that if you supply an input path to a symlink, it is invariably its target that is used for the operation; symlinks themselves cannot have icons associated with them.

See also: Icon Changer, a GUI utility that uses fileicon behind the scenes.


# Assign custom icon derived from image file 'img.png' to file 'foo':
fileicon set foo img.png

# Remove previously assigned custom icon from folder 'foodir':
fileicon rm foodir

# Extract custom icon from file 'foo' to icon file 'foo.icns':
fileicon get foo

# Test if folder 'foodir' has custom icon:
fileicon test foodir


Supported platforms:

  • macOS

Important: If you're running macOS 12.3 or higher, be sure to install at least version 0.3.1 of this utility, as it no longer relies on Python (which no longer ships with macOS).

Installation via Homebrew

With Homebrew installed, run the following:

brew install fileicon

Tip of the hat to @danielbayley for creating and submitting the formula.

Installation from the npm registry

With Node.js installed, install the package as follows:

[sudo] npm install fileicon -g


  • Whether you need sudo depends on how you installed Node.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
  • The -g ensures global installation and is needed to put fileicon in your system's $PATH.

Manual installation

  • Download the CLI as fileicon.
  • Make it executable with chmod +x fileicon.
  • Move it or symlink it to a folder in your $PATH, such as /usr/local/bin (requires sudo).


Find concise usage information below; for complete documentation, read the manual online, or, once installed, run man fileicon (fileicon --man if installed manually).

$ fileicon --help

Manage custom icons for files and folders on macOS.  

SET a custom icon for a file or folder:

    fileicon set      <fileOrFolder> [<imageFile>]

REMOVE a custom icon from a file or folder:

    fileicon rm       <fileOrFolder>

GET a file or folder's custom icon:

    fileicon get [-f] <fileOrFolder> [<iconOutputFile>]

    -f ... force replacement of existing output file

TEST if a file or folder has a custom icon:

    fileicon test     <fileOrFolder>

All forms: option -q silences status output.

Standard options: --help, --man, --version, --home


Copyright (c) 2015-2022 Michael Klement (, released under the MIT license.


This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D) denotes a development-time-only dependency, (O) an optional dependency, and (P) a peer dependency.

npm dependencies


Versioning complies with semantic versioning (semver).

  • v0.3.1 (2022-04-07):

    • [compatibility] Removed dependency on Python in favor of AppleScript with its ObjC bridge, courtesy of @scriptingosx
  • v0.3.0 (2022-02-11):

    • [compatibility] Added support for using an available python3 on macOS 12.3+, where the system v2.x /usr/bin/python will no longer be avaialble.
  • v0.2.4 (2019-12-10):

    • [installation] Thanks to @danielbayley, there is now an official Homebrew formula.
  • v0.2.3 (2019-11-01):

    • [enhancement] Installation via Homebrew is now possible on macOS.
    • [doc] updated with Homebrew installation instructions.
    • [dev] Updated dev-time-only packages to fix security issues.
  • v0.2.2 (2018-03-05):

    • [enhancement] filecon set <file> is now short for filecon set <file> <file>; that is, you can now more conveniently make an image file use itself as its icon.
  • v0.2.1 (2018-01-13):

    • [doc] Read-me improvements re supported image formats.
    • [enhancement] Improved wording of error message on attempting to use a pipe such as via a process subsitution (<(...)) in lieu of an actual image file, which is not supported.
  • v0.2.0 (2017-10-14):

    • [compatibility] macOS 10.13 (High Sierra) is now supported.
    • [enhancement] Switched from using sips -i for icon creation to a Python-based Cocoa call to NSWorkSpace.setIcon(_:forFile:options:), courtesy of As a result, icons in multiple resolutions are now generated, with a top resolution of 512 x 512 pixels (previously: 128 x 128)
    • [doc] More technical background added to
    • [usability] subcommands are now case-insensitive, and 'remove' is supported as an alias of 'rm'.
  • v0.1.8 (2016-04-21):

    • [dev] Refactored exit-code reporting for the 'get' command (no change in functionality.)
    • [dev] added.
  • v0.1.7 (2016-04-21):

    • [fix] Stored-npm-credentials detection code in the Makefile updated for newer npm versions.
    • [fix] Folder write test is now properly skipped for 'get' and 'test' commands - thanks, @zmwangx.
    • [fix] 'get' command now properly reports errors if icon extracton fails - thanks, @zmwangx.
    • [dev] Insignificant trailing whitespace removed - thanks, @zmwangx.
    • [dev] Added folder used by tests that was missing from the repo.
  • v0.1.6 (2015-09-16):

    • [doc] Man-page improvements.
    • [dev] Makefile improvements.
  • v0.1.5 (2015-09-15):

    • [doc] Man-page improvements.
    • [dev] Makefile improvements.
  • v0.1.4 (2015-09-14):

    • [fix] Spurious error message no longer prints when invoking fileicon --man on a system where the man page isn't installed.
    • [doc] Read-me improvements.
  • v0.1.3 (2015-09-02):

    • [dev, doc] minor tweaks
  • v0.1.2 (2015-08-04):

    • [doc] Read-me and manual enhancements.
  • v0.1.1 (2015-08-03):

    • [doc] Read-me and manual enhancements.
    • [dev] Permission-related tests added.
  • v0.1.0 (2015-08-03):

    • Initial release.


macOS CLI for managing custom icons for files and folders







No packages published

Contributors 4