{"id":13479377,"url":"https://github.com/mklement0/fileicon","last_synced_at":"2025-04-13T05:08:15.258Z","repository":{"id":35860962,"uuid":"40146005","full_name":"mklement0/fileicon","owner":"mklement0","description":"macOS CLI for managing custom icons for files and folders","archived":false,"fork":false,"pushed_at":"2023-07-24T14:01:57.000Z","size":1400,"stargazers_count":474,"open_issues_count":3,"forks_count":21,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-13T05:08:11.285Z","etag":null,"topics":["cli","custom-icon","filesystem","icons","macos"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mklement0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-08-03T20:19:01.000Z","updated_at":"2025-04-12T19:20:44.000Z","dependencies_parsed_at":"2024-01-14T09:00:39.683Z","dependency_job_id":null,"html_url":"https://github.com/mklement0/fileicon","commit_stats":{"total_commits":52,"total_committers":6,"mean_commits":8.666666666666666,"dds":"0.32692307692307687","last_synced_commit":"6508d97ed46e96698e4af9ca44d6666ac29a8cf0"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Ffileicon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Ffileicon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Ffileicon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Ffileicon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mklement0","download_url":"https://codeload.github.com/mklement0/fileicon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665747,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","custom-icon","filesystem","icons","macos"],"created_at":"2024-07-31T16:02:14.636Z","updated_at":"2025-04-13T05:08:15.237Z","avatar_url":"https://github.com/mklement0.png","language":"Shell","readme":"[![npm version](https://img.shields.io/npm/v/fileicon.svg)](https://npmjs.com/package/fileicon) [![license](https://img.shields.io/npm/l/fileicon.svg)](https://github.com/mklement0/fileicon/blob/master/LICENSE.md)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n**Contents**\n\n- [fileicon \u0026mdash; introduction](#fileicon-mdash-introduction)\n- [Examples](#examples)\n- [Installation](#installation)\n  - [Installation via Homebrew](#installation-via-homebrew)\n  - [Installation from the npm registry](#installation-from-the-npm-registry)\n  - [Manual installation](#manual-installation)\n- [Usage](#usage)\n- [License](#license)\n  - [Acknowledgements](#acknowledgements)\n  - [npm dependencies](#npm-dependencies)\n- [Changelog](#changelog)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# fileicon \u0026mdash; introduction\n\n`fileicon` is a macOS CLI for managing custom icons for files and folders, as \na programmatic alternative to interactively using Finder.\n\n`fileicon` allows assigning a custom icon to any file or folder,\nusing [any image file whose format is recognized by the system](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CocoaDrawingGuide/Images/Images.html#//apple_ref/doc/uid/TP40003290-CH208-BCIIFBJG).\n\n_Caveats_: \n * Custom icons rely on [extended attributes](https://en.wikipedia.org/wiki/Extended_file_attributes#OS_X) of the macOS filesystems, \n[HFS+](https://en.wikipedia.org/wiki/HFS_Plus) and [APFS](https://en.wikipedia.org/wiki/Apple_File_System).\nTherefore, custom icons are lost when copying files or folders to filesystems that don't\nsupport these attributes; for instance, custom icons cannot be stored in a Git repository.\n\n* v0.3.2+ supports custom icons for _volumes_ (folders that act as volume mountpoints) _in principle_, but, as of macOS 13.1 (Ventura), this often fails in practice, for reasons unknown to me; see [this Ask Different question](https://apple.stackexchange.com/q/451965/28668), for instance.\n\nWhen assigning an image file with `fileicon set`, a set of icons in several\nresolutions is created and stored in the resource fork of the target file itself\n/ of a hidden `Icon\\r` file inside the target folder / as the content of a hidden `.VolumeIcon.icns` file for folders that are _volume mountpoints_. Addtionally, a `com.apple.FinderInfo` extended attribute with the custom-icon attribute (flag) is set on the target file or folder itself.\n\nThe icon with the highest resolution measures 512 x 512 pixels, and the input\nimage is scaled accordingly.  \nNote that input images that aren't square can result in distorted icons;\nfor best results, provide square images.\n\nIf you supply an input path to a _symlink_, it is invariably its\n_target_ that is used for the operation; symlinks themselves cannot have\nicons associated with them.\n\nSee also: [Icon Changer](https://github.com/chris1111/Icon-Changer), a GUI utility that uses `fileicon` behind the scenes.\n\n# Examples\n\n```sh\n# Assign custom icon derived from image file 'img.png' to file 'foo':\nfileicon set foo img.png\n\n# Remove previously assigned custom icon from folder 'foodir':\nfileicon rm foodir\n\n# Extract custom icon from file 'foo' to icon file 'foo.icns':\nfileicon get foo\n\n# Test if folder 'foodir' has custom icon:\nfileicon test foodir\n```\n\n# Installation\n\n**Supported platforms:**\n\n* **macOS**\n\n**Important**: \n * If you're running macOS 12 (Monterey) or higher, be sure to install at least version 0.3.1 of this utility,\nas it no longer relies on Python (which no longer ships with macOS).\n * Unfortunately, a bug beyond `fileicon`'s control causes the `get` sub-command (for extracting an existing icon) to be excessively slow on macOS 12 (Monterey); this has been fixed in macOS 13 (Ventura).\n\n## Installation via Homebrew\n\nWith [Homebrew](https://brew.sh/) installed, run the following:\n\n```sh\nbrew install fileicon\n```\n\n\u003csup\u003eTip of the hat to [@danielbayley](https://github.com/danielbayley) for creating and submitting the formula.\u003c/sup\u003e\n\n## Installation from the npm registry\n\nWith [Node.js](http://nodejs.org/) installed, install [the package](https://www.npmjs.com/package/fileicon) as follows:\n\n```sh\n[sudo] npm install fileicon -g\n```\n\n**Note**:\n\n* Whether you need `sudo` depends on how you installed Node.js and whether you've [changed permissions later](https://docs.npmjs.com/getting-started/fixing-npm-permissions); if you get an `EACCES` error, try again with `sudo`.\n* The `-g` ensures [_global_ installation](https://docs.npmjs.com/getting-started/installing-npm-packages-globally) and is needed to put `fileicon` in your system's `$PATH`.\n\n## Manual installation\n\n* Download [the CLI](https://raw.githubusercontent.com/mklement0/fileicon/stable/bin/fileicon) as `fileicon`.\n* Make it executable with `chmod +x fileicon`.\n* Move it or symlink it to a folder in your `$PATH`, such as `/usr/local/bin` (requires `sudo`).\n\n# Usage\n\nFind concise usage information below; for complete documentation, read the [manual online](doc/fileicon.md), or, once installed, run `man fileicon` (`fileicon --man` if installed manually).\n\n\u003c!-- DO NOT EDIT THE FENCED CODE BLOCK and RETAIN THIS COMMENT: The fenced code block below is updated by `make update-readme/release` with CLI usage information. --\u003e\n\n```nohighlight\n$ fileicon --help\n\n\nManage custom icons for files and folders on macOS.  \n\nSET a custom icon for a file or folder:\n\n    fileicon set      \u003cfileOrFolder\u003e [\u003cimageFile\u003e]\n\nREMOVE a custom icon from a file or folder:\n\n    fileicon rm       \u003cfileOrFolder\u003e\n\nGET a file or folder's custom icon:\n\n    fileicon get [-f] \u003cfileOrFolder\u003e [\u003ciconOutputFile\u003e]\n\n    -f ... force replacement of existing output file\n\nTEST if a file or folder has a custom icon:\n\n    fileicon test     \u003cfileOrFolder\u003e\n\nAll forms: option -q silences status output.\n\nStandard options: --help, --man, --version, --home\n```\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'LICENSE.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n# License\n\nCopyright (c) 2015-2022 Michael Klement \u003cmklement0@gmail.com\u003e (http://same2u.net), released under the [MIT license](https://spdx.org/licenses/MIT#licenseText).\n\n## Acknowledgements\n\nThis project gratefully depends on the following open-source components, according to the terms of their respective licenses.\n\n[npm](https://www.npmjs.com/) 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.\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the dependencies from 'package.json'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n## npm dependencies\n\n* [doctoc (D)]()\n* [json (D)]()\n* [marked (D)](https://marked.js.org)\n* [marked-man (D)]()\n* [replace (D)]()\n* [semver (D)]()\n* [urchin (D)]()\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'CHANGELOG.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n# Changelog\n\nVersioning complies with [semantic versioning (semver)](http://semver.org/).\n\n\u003c!-- NOTE: An entry template for a new version is automatically added each time `make version` is called. Fill in changes afterwards. --\u003e\n\n* ** v0.3.4 == [v0.3.3](https://github.com/mklement0/fileicon/compare/v0.3.2...v0.3.3)** (2023-03-02):\n  * [fix] Fix for [#42](https://github.com/mklement0/fileicon/issues/42), courtesy of [vszakats](https://github.com/vszakats).\n\n* **[v0.3.2](https://github.com/mklement0/fileicon/compare/v0.3.1...v0.3.2)** (2022-12-29):\n  * [enhancement] Support for *volume* icons, at least in principle; **caveat**: as of macOS 13.1, this often fails in practice; see https://apple.stackexchange.com/q/451965/28668 for an example.\n\n* **[v0.3.1](https://github.com/mklement0/fileicon/compare/v0.3.0...v0.3.1)** (2022-04-07):\n  * [compatibility] Removed dependency on Python in favor of AppleScript with its ObjC bridge, courtesy of [@scriptingosx](https://github.com/scriptingosx)\n\n* **[v0.3.0](https://github.com/mklement0/fileicon/compare/v0.2.4...v0.3.0)** (2022-02-11):\n  * [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.\n\n* **[v0.2.4](https://github.com/mklement0/fileicon/compare/v0.2.3...v0.2.4)** (2019-12-10):\n  * [installation] Thanks to @danielbayley, there is now an official Homebrew formula.\n\n* **[v0.2.3](https://github.com/mklement0/fileicon/compare/v0.2.2...v0.2.3)** (2019-11-01):\n  * [enhancement] Installation via Homebrew is now possible on macOS.\n  * [doc] `README.md` updated with Homebrew installation instructions.\n  * [dev] Updated dev-time-only packages to fix security issues.\n\n* **[v0.2.2](https://github.com/mklement0/fileicon/compare/v0.2.1...v0.2.2)** (2018-03-05):\n  * [enhancement] `filecon set \u003cfile\u003e` is now short for `filecon set \u003cfile\u003e \u003cfile\u003e`; that is, you can now more \n    conveniently make an image file use itself as its icon.\n\n* **[v0.2.1](https://github.com/mklement0/fileicon/compare/v0.2.0...v0.2.1)** (2018-01-13):\n  * [doc] Read-me improvements re supported image formats.\n  * [enhancement] Improved wording of error message on attempting to use a pipe\n    such as via a process subsitution (`\u003c(...)`) in lieu of an actual image file,\n    which is not supported.\n\n* **[v0.2.0](https://github.com/mklement0/fileicon/compare/v0.1.10...v0.2.0)** (2017-10-14):\n  * [compatibility] macOS 10.13 (High Sierra) is now supported.\n  * [enhancement] Switched from using `sips -i` for icon creation to a Python-based\n                  Cocoa call to `NSWorkSpace.setIcon(_:forFile:options:)`, courtesy of https://apple.stackexchange.com/a/161984/28668\n                  As a result, icons in multiple resolutions are now generated, with a top resolution of 512 x 512 pixels (previously: 128 x 128)\n  * [doc] More technical background added to `README.md`.\n  * [usability] subcommands are now case-insensitive, and 'remove' is supported as an alias of 'rm'.\n\n* **[v0.1.8](https://github.com/mklement0/fileicon/compare/v0.1.7...v0.1.8)** (2016-04-21):\n  * [dev] Refactored exit-code reporting for the 'get' command (no change in functionality.)\n  * [dev] `TODO.md` added.\n\n* **[v0.1.7](https://github.com/mklement0/fileicon/compare/v0.1.6...v0.1.7)** (2016-04-21):\n  * [fix] Stored-npm-credentials detection code in the Makefile updated for\n          newer npm versions.\n  * [fix] Folder write test is now properly skipped for 'get' and 'test'\n          commands - thanks, @zmwangx.\n  * [fix] 'get' command now properly reports errors if icon extracton fails\n           - thanks, @zmwangx.\n  * [dev] Insignificant trailing whitespace removed - thanks, @zmwangx.  \n  * [dev] Added folder used by tests that was missing from the repo.\n\n* **[v0.1.6](https://github.com/mklement0/fileicon/compare/v0.1.5...v0.1.6)** (2015-09-16):\n  * [doc] Man-page improvements.\n  * [dev] Makefile improvements.\n\n* **[v0.1.5](https://github.com/mklement0/fileicon/compare/v0.1.4...v0.1.5)** (2015-09-15):\n  * [doc] Man-page improvements.\n  * [dev] Makefile improvements.\n\n* **[v0.1.4](https://github.com/mklement0/fileicon/compare/v0.1.3...v0.1.4)** (2015-09-14):\n  * [fix] Spurious error message no longer prints when invoking `fileicon --man` on a system where the man page isn't installed.\n  * [doc] Read-me improvements.\n\n* **[v0.1.3](https://github.com/mklement0/fileicon/compare/v0.1.2...v0.1.3)** (2015-09-02):\n  * [dev, doc] minor tweaks\n\n* **[v0.1.2](https://github.com/mklement0/fileicon/compare/v0.1.1...v0.1.2)** (2015-08-04):\n  * [doc] Read-me and manual enhancements.\n\n* **[v0.1.1](https://github.com/mklement0/fileicon/compare/v0.1.0...v0.1.1)** (2015-08-03):\n  * [doc] Read-me and manual enhancements.\n  * [dev] Permission-related tests added.\n\n* **v0.1.0** (2015-08-03):\n  * Initial release.\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmklement0%2Ffileicon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmklement0%2Ffileicon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmklement0%2Ffileicon/lists"}