# ⚠️ `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
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](https://mastodon.social/@lgarron) or [let me know](https://github.com/lgarron/folderify/issues/new) and I'd love to feature some real-world uses!
# Install using [Homebrew](https://formulae.brew.sh/formula/folderify)
```shell
brew install folderify
```
# Usage
Use a mask to assign an icon to a folder:
```shell
folderify mask.png /path/to/folder
```
Generate `mask.icns` and `mask.iconset` files:
```shell
folderify mask.png
```
Generate icon files for a specific version of macOS (the default is your current
version):
```shell
folderify --macOS 11.0 mask.png
```
By default, `folderify` uses your system's current light/dark mode. Use `--color-scheme` to override this:
```shell
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`
```shell
pip install folderify
```
## Download the source code directly
Or download the code directly:
```shell
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.
```shell
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](https://www.imagemagick.org/) - for image processing (you should be able to run <code>convert</code> and <code>identify</code> on the commandline).
- Included with macOS:
- Python (version 2 or 3).
- `iconutil`
- Bundled with `folderify`:
- [`osxiconutils`](https://github.com/sveinbjornt/osxiconutils), a GPL-licensed project by Sveinbjorn Thordarson (based on [`IconFamily`](http://iconfamily.sourceforge.net/)).
- 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:
Raw data
{
"_id": null,
"home_page": "https://github.com/lgarron/folderify",
"name": "folderify",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "icon macOS OSX Mac Darwin graphics folder imagemagick",
"author": "Lucas Garron",
"author_email": "code@garron.net",
"download_url": "https://files.pythonhosted.org/packages/ff/72/ded686a8eeea54b0ffb0789f050597211e37d4e346b20364d634911a9ef4/folderify-2.4.2.tar.gz",
"platform": null,
"description": "# \u26a0\ufe0f `folderify` v2 \u26a0\ufe0f\n\nThis 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\n\n--------\n\n# folderify\n\n\n\nGenerate pixel-perfect macOS folder icons in the native style.\n\n- Works for OS X 10.5 (Leopard) through macOS 13 (Ventura).\n- Automatically includes all icon sizes from `16x16` through `512x512@2x`.\n- Light or dark mode (automatically selected by default).\n\n**Using `folderify`?** [Let me know](https://mastodon.social/@lgarron) or [let me know](https://github.com/lgarron/folderify/issues/new) and I'd love to feature some real-world uses!\n\n# Install using [Homebrew](https://formulae.brew.sh/formula/folderify)\n\n```shell\nbrew install folderify\n```\n\n# Usage\n\nUse a mask to assign an icon to a folder:\n\n```shell\nfolderify mask.png /path/to/folder\n```\n\nGenerate `mask.icns` and `mask.iconset` files:\n\n```shell\nfolderify mask.png\n```\n\nGenerate icon files for a specific version of macOS (the default is your current\nversion):\n\n```shell\nfolderify --macOS 11.0 mask.png\n```\n\nBy default, `folderify` uses your system's current light/dark mode. Use `--color-scheme` to override this:\n\n```shell\nfolderify --macOS 11.0 --color-scheme dark mask.png\n```\n\nNote:\n\n- 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.\n- Dark color scheme is only supported for macOS 11.0 (and later) right now.\n\n## Tips\n\nFor best results:\n\n- Use a `.png` mask.\n- Use a solid black design over a transparent background.\n- Make sure the corner pixels of the mask image are transparent. They are used for empty margins.\n- Pass the `--no-trim` flag and use a mask:\n - with a height of 384px,\n - with a width that is a multiple of 128px (up to 768px),\n - using a 16px grid.\n - Each 64x64 tile will exactly align with 1 pixel at the smallest icon size.\n\n# Other installation options\n\nIf you don't have Homebrew but you already have ImageMagick (the `convert`\nbinary) on your system, you can use the following:\n\n## Install using `pip`\n\n```shell\npip install folderify\n```\n\n## Download the source code directly\n\nOr download the code directly:\n\n```shell\ncurl -L https://github.com/lgarron/folderify/archive/main.zip -o folderify-main.zip\nunzip folderify-main.zip && cd folderify-main\npython -m folderify examples/src/folder_outline.png . --reveal\n```\n\nThe repository folder should now have a custom icon.\n\n```shell\nfor file in examples/src/*.png; do python -m folderify $file; done\nopen examples/src/\n```\n\nYou should see a bunch of new `.iconset` folders and `.icns` files that were automatically generated from the `.png` masks.\n\n## Dependencies\n\n- [ImageMagick](https://www.imagemagick.org/) - for image processing (you should be able to run <code>convert</code> and <code>identify</code> on the commandline).\n- Included with macOS:\n - Python (version 2 or 3).\n - `iconutil`\n- Bundled with `folderify`:\n - [`osxiconutils`](https://github.com/sveinbjornt/osxiconutils), a GPL-licensed project by Sveinbjorn Thordarson (based on [`IconFamily`](http://iconfamily.sourceforge.net/)).\n- Optional:\n - `sips`, `DeRez`, `Rez`, `SetFile` (You need XCode command line tools for some of these.)\n - Only used if you use `--set-icon-using Rez` in the arguments.\n\n# Full options\n\n```\nusage: folderify [-h] [--reveal] [--macOS VERSION] [--osx VERSION]\n [--color-scheme COLOR_SCHEME] [--no-trim]\n [--set-icon-using TOOL] [--verbose]\n [mask] [target]\n\nGenerate a native-style macOS folder icon from a mask file.\n\npositional arguments:\n mask Mask image file. For best results:\n - Use a .png mask.\n - Use a solid black design over a transparent background.\n - Make sure the corner pixels of the mask image are transparent. They are used for empty margins.\n - Make sure the non-transparent pixels span a height of 384px, using a 16px grid.\n 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.\n target Target file or folder. If a target is specified, the resulting icon will be applied to the target file/folder.\n 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).\n\noptional arguments:\n -h, --help show this help message and exit\n --reveal, -r Reveal the target (or resulting .icns file) in Finder.\n --macOS VERSION Version of the macOS folder icon, e.g. \"10.13\". Defaults to the version currently running (10.16).\n --osx VERSION, -x VERSION\n Synonym for the --macOS argument.\n --color-scheme COLOR_SCHEME\n Color scheme: auto (match current system), light, dark.\n --no-trim Don't trim margins from the mask. By default, transparent margins are trimmed from all 4 sides.\n --set-icon-using TOOL\n Tool to used to set the icon of the target: auto (default), seticon, Rez.\n 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.\n --verbose, -v Detailed output.\n\n```\n\n---\n\nExample generated from the Apple logo:\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate pixel-perfect macOS folder icons in the native style.",
"version": "2.4.2",
"split_keywords": [
"icon",
"macos",
"osx",
"mac",
"darwin",
"graphics",
"folder",
"imagemagick"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2bb9c56a052d8a810f65574413f6b6596150de166476a10ba94774a00f7598c8",
"md5": "8f2a2299ec0a18b4e45be37aeb5cdb7e",
"sha256": "6d06e3ea7dad539d5102dc5498f17e5455e76c85619e2dff397764fd4b538bb4"
},
"downloads": -1,
"filename": "folderify-2.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f2a2299ec0a18b4e45be37aeb5cdb7e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5658197,
"upload_time": "2023-04-13T22:30:37",
"upload_time_iso_8601": "2023-04-13T22:30:37.257413Z",
"url": "https://files.pythonhosted.org/packages/2b/b9/c56a052d8a810f65574413f6b6596150de166476a10ba94774a00f7598c8/folderify-2.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ff72ded686a8eeea54b0ffb0789f050597211e37d4e346b20364d634911a9ef4",
"md5": "c4308cc80f6dade44d880d80dd736d9d",
"sha256": "b5f5500f8f9f5264c61f556c85c652de490999cf69ad9e33311cf206f3bd0c2c"
},
"downloads": -1,
"filename": "folderify-2.4.2.tar.gz",
"has_sig": false,
"md5_digest": "c4308cc80f6dade44d880d80dd736d9d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5644590,
"upload_time": "2023-04-13T22:30:50",
"upload_time_iso_8601": "2023-04-13T22:30:50.905478Z",
"url": "https://files.pythonhosted.org/packages/ff/72/ded686a8eeea54b0ffb0789f050597211e37d4e346b20364d634911a9ef4/folderify-2.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-13 22:30:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "lgarron",
"github_project": "folderify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "folderify"
}
JSON
