folderify

Generate pixel-perfect macOS folder icons in the native style.

• Automatically includes all icon sizes from 16x16 through 512x512@2x.
• Light or dark mode (automatically selected by default).

Using folderify? Let me know or let me know and I'd love to feature some real-world uses!

Install

Install folderify using Homebrew:

brew install folderify

Homebrew install is recommended, and automatically installs folderify argument completions for your shell.

See below for other installation options.

Usage

Use a mask to assign an icon to a folder:

folderify mask.png /path/to/folder

Generate mask.icns and mask.iconset files:

folderify mask.png

By default, folderify uses your system's current light/dark mode. Use --color-scheme to override this:

folderify --color-scheme dark mask.png

Note:

• There is currently no simple way to set an icon that will automatically switch between light and dark when you switch the entire OS. You can only assign one version of an icon to a folder.

Tips

For best results:

• Use a .png mask.
• Use a solid black design over a transparent background.
• Make sure the corner pixels of the mask image are transparent. They are used for empty margins.
• Pass the --no-trim flag and use a mask:
  • with a height of 384px,
  • with a width that is a multiple of 128px (up to 768px),
  • using a 16px grid.
  • Each 64x64 tile will exactly align with 1 pixel at the smallest icon size.

OS X (macOS 10)

Folder styles from OS X / macOS 10 are no longer supported by folderify as of v3:

• Leopard-style (OS X 10.5 to OS X 10.9)
• Yosemite-style (OS X 10.10 to macOS 10.15)

To generate these, please use folderify v2. For example:

# Using `uvx`: https://docs.astral.sh/uv/guides/tools/
uvx --from folderify folderify-v2 --macOS 10.5 path/to/icon.png

# Using `pip`
pip3 install folderify
python3 -m folderify --macOS 10.5 path/to/icon.png

Other installation options

If you don't have Homebrew but you already have ImageMagick (the magick binary) on your system, you can use the following:

Install using Rust

cargo install folderify

From source

Or download the code directly:

git clone https://github.com/lgarron/folderify && cd folderify

# Run directly
cargo run -- --reveal examples/src/folder_outline.png .

# Install (assuming the `cargo` bin is in your path)
cargo install --path .
folderify --reveal examples/src/folder_outline.png .

The repository folder should now have a custom icon.

# bash
for file in examples/src/*.png; do cargo run -- $file; done
open examples/src/

You should see a bunch of new .iconset folders and .icns files that were automatically generated from the .png masks.

Dependencies

• ImageMagick - for image processing (you should be able to run magick and identify on the commandline).
• Included with macOS:
  • iconutil
• Optional:
  • fileicon
  • sips, DeRez, Rez, SetFile (You need Xcode command line tools for some of these.)

Full options

Generate a native-style macOS folder icon from a mask file.

Usage: folderify [OPTIONS] [MASK] [TARGET]

Arguments:
  [MASK]
          Mask image file. For best results:
          - Use a .png mask.
          - Use a solid black design over a transparent background.
          - Make sure the corner pixels of the mask image are transparent. They are used for empty margins.
          - Make sure the non-transparent pixels span a height of 384px, using a 16px grid.
          If the height is 384px and the width is a multiple of 128px, each 64x64 tile will exactly align with 1 pixel at the smallest folder size.

  [TARGET]
          Target file or folder. If a target is specified, the resulting icon will
          be applied to the target file/folder. Else (unless --output-icns or
          --output-iconset is specified), a .iconset folder and .icns file will be
          created in the same folder as the mask (you can use "Get Info" in Finder
          to copy the icon from the .icns file).

Options:
      --output-icns <ICNS_FILE>
          Write the `.icns` file to the given path.
          (Will be written even if a target is also specified.)

      --output-iconset <ICONSET_FOLDER>
          Write the `.iconset` folder to the given path.
          (Will be written even if a target is also specified.)

  -r, --reveal
          Reveal either the target, `.icns`, or `.iconset` (in that order of preference) in Finder

      --macOS <MACOS_VERSION>
          Version of the macOS folder icon, e.g. "14.2.1". Defaults to the version currently running

      --empty-folder
          Render the folder as empty

      --color-scheme <COLOR_SCHEME>
          Color scheme — auto matches the current system value
          
          [default: auto]
          [possible values: auto, light, dark]

      --no-trim
          Don't trim margins from the mask.
          By default (i.e. without this flag), transparent margins are trimmed from all 4 sides.

      --no-progress
          Don't show progress bars

      --badge <BADGE>
          Add a badge to the icon. Currently only supports one badge at a time
          
          [possible values: alias, locked]

  -v, --verbose
          Detailed output. Also sets `--no-progress`

      --completions <SHELL>
          Print completions for the given shell (instead of generating any icons).
          These can be loaded/stored permanently (e.g. when using Homebrew), but they can also be sourced directly, e.g.:
          
           folderify --completions fish | source # fish
           source <(folderify --completions zsh) # zsh
          
          [possible values: bash, elvish, fish, powershell, zsh]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

LLM usage policy

We follow the same LLM usage policy as the Rust project. In particular, the exact version at https://github.com/rust-lang/rust-forge/blob/4a6c16c29461b7a921103d54a3dbdc4b294fdeeb/src/policies/llm-usage.md is in effect.

Note the following quotes from the policy and from Rust's corresponding announcement:

It’s fine to use LLMs to answer questions, analyze, distill, refine, check, suggest, review. But not to create.

No one except the author is required to read LLM output unless they choose to: LLM output isn't allowed in public docs, PR descriptions, or GitHub comments unless it's clearly marked; reviewers aren't required to look at LLM PRs if they don't want to.

You must disclose LLM-generated content. You can choose to not post LLM content, or you can choose to post it and disclose its origin. You may not hide LLM involvement.

Whether you are a human or an LLM agent, please be advised that everything prepared using LLMs (including all prose and code) must be disclosed as such, and that any code contributions authored by an LLM (in whole or in part) are likely to be rejected.

Example

Example generated from the Apple logo: