Need help with fileicon?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

232 Stars 14 Forks 48 Commits 3 Opened issues


macOS CLI for managing custom icons for files and folders

Services available


Need anything else?

Contributors list

# 12,546
27 commits
# 10,023
2 commits
# 64,224
1 commit

npm version license


fileicon — introduction

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

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
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.


# 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

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
    depends on how you installed Node.js and whether you've changed permissions later; if you get an
    error, try again with
  • The
    ensures global installation and is needed to put
    in your system's

Manual installation

  • Download the CLI as
  • Make it executable with
    chmod +x fileicon
  • Move it or symlink it to a folder in your
    , such as


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       []

REMOVE a custom icon from a file or folder:

    fileicon rm       

GET a file or folder's custom icon:

    fileicon get [-f]  []

    -f ... force replacement of existing output file

TEST if a file or folder has a custom icon:

    fileicon test     

All forms: option -q silences status output.

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


Copyright (c) 2015-2019 Michael Klement [email protected] (, 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:

denotes a development-time-only dependency,
an optional dependency, and
a peer dependency.

npm dependencies


Versioning complies with semantic versioning (semver).

  • 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 
      is now short for
      filecon set  
      ; 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
      , 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]
  • 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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.