Wondering what’s next for npm?Check out our public roadmap! »


    0.2.4 • Public • Published

    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.


    # 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 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-2019 Michael Klement mklement0@gmail.com (http://same2u.net), 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.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] README.md 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 https://apple.stackexchange.com/a/161984/28668 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 README.md.
      • [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] TODO.md 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.


    npm i fileicon

    DownloadsWeekly Downloads






    Unpacked Size

    74.7 kB

    Total Files


    Last publish


    • avatar