IconChanger: custom macOS icons with a GUI and a CLI

What changes when an icon changes on macOS

The problem is small and specific. macOS gives every application and folder the icon the developer shipped, and there is no supported preference to swap it for a picture you like. A user with a large Applications folder, a lot of browser profiles, or a mix of tools and personal scripts ends up with a Dock full of near-identical blue documents, and the only practical fix is to replace the icon resource inside each application bundle, which is exactly what this project does. The Dock preview is the feature the README leads with, and the reason is that the Dock is where the visual difference is actually felt. The scope is broader than applications, because folder icons are covered too, and the project keeps favourites and history so that an icon you liked can be found again later. Thirty languages are covered, and the documentation site covers setup guides, the CLI commands, the API configuration, the background service, and import and export, which is a useful hint about how much there is beyond the window. The audience is a Mac user with admin rights who wants a personalised Finder and Dock, not a developer tool in the usual sense, although the CLI and the API configuration make it scriptable.

Two install paths, and the privilege you will be asked for

Installation is either one command or a download, and the README gives both.

brew install Bengerthelorf/tap/iconchanger

The manual route is to download the latest DMG from the Releases page, drag it into Applications, and launch it. The system requirements are short and one of them matters: macOS 13.0 or later, and administrator privileges. The privilege requirement is not an accident of packaging. Changing an application icon means writing into a bundle that the system and the application vendor own, and the owner of that bundle is often not your user account. The tool asks for elevation because the operation genuinely needs it, and you should understand that before you grant it, since it means the tool can write outside your home directory on every change. The Homebrew route is the one to prefer if you already manage your Mac with a package manager, because it keeps the app in the same update flow as everything else. The DMG route leaves you responsible for updates, and the project does publish release artifacts for that case.

A separate command line tool, not just a GUI with flags

The repository layout is worth a look, because it shows the shape of the project. There is an IconChanger.xcodeproj, an IconChanger directory for the application, and a separate IconChangerCLI directory, so the command line surface is a distinct product rather than a hidden mode of the GUI. The README describes the CLI as full featured and aimed at scripting and automation, and the documentation site lists the CLI commands among its topics. That distinction is what makes the tool interesting to an engineer rather than only to a person who wants their Dock to look nicer. A GUI is a fine way to pick an icon for one application and a poor way to apply a policy to forty of them across a fleet of Macs, and the separate CLI is what makes the second case possible. The other structural pieces visible in the repository support the same idea: a scripts directory, a tests directory, and a translations directory, the last of which lines up with the claim of thirty languages and with the crowd of readme translations in Chinese and French alongside the English one.

The background service and the problem of the app update

The single most interesting feature in the highlights list is the background service, described as auto restore of icons on a schedule or after app updates. That points at the real failure mode of this whole category of tool. When macOS updates an application, the vendor supplies a new bundle, and the icon you replaced is gone, because the update replaced the whole thing. Any tool that edits the bundle inherits that fragility, and a user who has personalised fifteen applications is left restoring them by hand after every round of system updates. Scheduling the restore handles the other half of the same problem, the case where a change is lost for reasons other than an update, such as a reinstall or a restore from a backup. The service therefore converts a one-off tweak into a persistent state, which is what separates this from a one-line command you run once. The trade-off is that the service has to run in the background with elevated permissions, and a background process that holds admin rights on a desktop is a real cost that the README does not discuss. If your workflow is a scripted set of images applied on a fresh machine, you would rather set icons once and not have a daemon running.

macOSicons.com, favourites, history and import and export

The source of the icons is a third party service, macOSicons.com, which the README describes as an icon database and which is credited in the acknowledgements alongside the original project and the tool the project is based on. The documentation site also lists API configuration among its topics, which fits a service integration, since fetching icons programmatically needs a key and an endpoint. That is the clearest external dependency in the project, and it is worth naming explicitly as a design choice rather than burying: the icon catalogue is somebody else's, the tool is the part that applies it. Around that, the project keeps favourites and history, so your choices are recorded and reusable, and the documentation lists import and export, which is the mechanism for moving a setup between machines or sharing one. For a personal Mac, favourites plus a documented export path covers the realistic scenarios, and it is a differentiator against a tool that only lets you point at a picture file you already have.

Two forks, a helper tool and an original project

The acknowledgements section is unusually informative about lineage, and it explains a lot about the current state of the code. The project credits underthestars-zhy's IconChanger as the original project, and lcandy2 as the project this fork is based on, along with macOSicons.com as the icon database, the fileicon tool by mklement0 as the icon manipulation tool, and a contributor named Atom. So this is a second generation fork of a first generation fork, and the icon mechanics lean on fileicon rather than on something written from scratch. That has an obvious upside, in that the low level work of writing icon resources and refreshing the Finder is a solved problem delegated to a dedicated helper tool, and an obvious cost, in that a behaviour you dislike may live in the dependency rather than in this repository. The README also notes a Sparkle presence in the repository topics, which is the conventional macOS framework for in-app updates, and there is a SECURITY.md alongside the code, so the project has at least the outline of a responsible disclosure path. The contributing instructions are a one-liner: fork, clone, open in Xcode 15 or later, and start contributing, which tells you the whole toolchain expectation in a single sentence.

Release naming that tells you where you stand

The publication history is unusual enough to read carefully. The three most recent releases are named IconChanger v1.5.1-pre.1.fix.3 from 2026-07-30, v1.5.1-pre.1.fix.2 from the same day, and v1.5.1-pre.1.fix.1 from 2026-07-29, and the last push to the repository was on 2026-07-30. Every one of those tags is a pre-release name with a pre component and a fix component, and three of them shipped within a day of each other. That pattern says two things. The project is being iterated on quickly, probably on the back of user reports, and the published artefacts are not a clean stable line. If you install from Homebrew, you are relying on the tap to pick something sensible, and if you install from a DMG, you should look at the tag before you download it. The licence is MIT, which permits redistribution and modification in commercial and closed source work with the notice retained, and the README points to the LICENSE file for the details. The documentation lives at app.snaix.homes/iconchanger, and the README also points to a Getting Started guide, which is where to look before granting administrator rights for the first time.

Editorial conclusion

Adopt IconChanger if you want to change application and folder icons on a Mac you manage, and if you want the change to survive an app update, because the background service is the part that solves the problem every other approach leaves you to fix by hand. It does not fit a machine you do not administer, since the README lists administrator privileges as a requirement, and it does not fit a Mac below macOS 13. Before you install it, check the release tag you pick, because the recent published versions carry pre-release names such as v1.5.1-pre.1.fix.3 rather than a clean stable number, and decide whether the macOSicons.com integration and the network access it implies fit your environment.

Frequently asked questions

Official sources

1. Bengerthelorf/macIconChanger on GitHub
2. License: MIT
3. Project website
4. README
5. Releases