Skip to main content

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

Project description

⚠️ folderify v2 ⚠️

This is folderify v2 (implemented in Python and published to PyPI), which is no longer officially supported. Unless you need folder icons for macOS 10.15 or earlier, please consider updating to folderify v3: https://github.com/lgarron/folderify/tree/main#install


folderify

mask.png + folder = folderified!

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

  • Works for OS X 10.5 (Leopard) through macOS 13 (Ventura).
  • 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 using Homebrew

brew install folderify

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

Generate icon files for a specific version of macOS (the default is your current version):

folderify --macOS 11.0 mask.png

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

folderify --macOS 11.0 --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.
  • Dark color scheme is only supported for macOS 11.0 (and later) right now.

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.

Other installation options

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

Install using pip

pip install folderify

Download the source code directly

Or download the code directly:

curl -L https://github.com/lgarron/folderify/archive/main.zip -o folderify-main.zip
unzip folderify-main.zip && cd folderify-main
python -m folderify examples/src/folder_outline.png . --reveal

The repository folder should now have a custom icon.

for file in examples/src/*.png; do python -m folderify $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 convert and identify on the commandline).
  • Included with macOS:
    • Python (version 2 or 3).
    • iconutil
  • Bundled with folderify:
  • Optional:
    • sips, DeRez, Rez, SetFile (You need XCode command line tools for some of these.)
      • Only used if you use --set-icon-using Rez in the arguments.

Full options

usage: folderify [-h] [--reveal] [--macOS VERSION] [--osx VERSION]
                   [--color-scheme COLOR_SCHEME] [--no-trim]
                   [--set-icon-using TOOL] [--verbose]
                   [mask] [target]

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

positional 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, 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).

optional arguments:
  -h, --help            show this help message and exit
  --reveal, -r          Reveal the target (or resulting .icns file) in Finder.
  --macOS VERSION       Version of the macOS folder icon, e.g. "10.13". Defaults to the version currently running (10.16).
  --osx VERSION, -x VERSION
                        Synonym for the --macOS argument.
  --color-scheme COLOR_SCHEME
                        Color scheme: auto (match current system), light, dark.
  --no-trim             Don't trim margins from the mask. By default, transparent margins are trimmed from all 4 sides.
  --set-icon-using TOOL
                        Tool to used to set the icon of the target: auto (default), seticon, Rez.
                        Rez usually produces a smaller "resource fork" for the icon, but only works if XCode command line tools are already installed and if you're using a folder target.
  --verbose, -v         Detailed output.


Example generated from the Apple logo: Icons from apple.iconset at resolutions from 16x16  up to 512x5125@2x, shown in Quicklook on macOS

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

folderify-2.4.2.tar.gz (5.6 MB view details)

Uploaded Source

Built Distribution

folderify-2.4.2-py3-none-any.whl (5.7 MB view details)

Uploaded Python 3

File details

Details for the file folderify-2.4.2.tar.gz.

File metadata

  • Download URL: folderify-2.4.2.tar.gz
  • Upload date:
  • Size: 5.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.6

File hashes

Hashes for folderify-2.4.2.tar.gz
Algorithm Hash digest
SHA256 b5f5500f8f9f5264c61f556c85c652de490999cf69ad9e33311cf206f3bd0c2c
MD5 c4308cc80f6dade44d880d80dd736d9d
BLAKE2b-256 ff72ded686a8eeea54b0ffb0789f050597211e37d4e346b20364d634911a9ef4

See more details on using hashes here.

File details

Details for the file folderify-2.4.2-py3-none-any.whl.

File metadata

  • Download URL: folderify-2.4.2-py3-none-any.whl
  • Upload date:
  • Size: 5.7 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.6

File hashes

Hashes for folderify-2.4.2-py3-none-any.whl
Algorithm Hash digest
SHA256 6d06e3ea7dad539d5102dc5498f17e5455e76c85619e2dff397764fd4b538bb4
MD5 8f2a2299ec0a18b4e45be37aeb5cdb7e
BLAKE2b-256 2bb9c56a052d8a810f65574413f6b6596150de166476a10ba94774a00f7598c8

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page