Creating ICNS files for macOS apps: A developer's guide

10 min read

Updated: September 9, 2023

You’ve built an amazing macOS app, but you’re stuck on how to create the ICNS icon file for it. Don’t worry, you’re not alone. Learn how to create ICNS icon file for your macOS app with this straightforward guide. We’ll cover essential sizes, naming rules, and technical steps—all using free tools. This article is a must-read for developers looking to make their macOS app icons look professional.

Introduction

Developing a macOS app is an exciting journey, one that involves various steps from conceptualization to coding. However, before you unveil your masterpiece to the world, there’s one crucial element that often goes overlooked—the app icon. An app icon is not just a visual placeholder; it’s the first impression users get of your application. And as we all know, first impressions matter.

The hurdle often comes in when you need to convert your beautiful icon design into a technical ICNS file that macOS can use. This involves understanding a range of sizes, pixel densities, and naming conventions. Sure, there are paid tools that can do this for you, but what if you could accomplish it all for free?

This is where this guide steps in. We’ll walk you through the process of creating an ICNS icon file for your macOS app, covering all the necessary sizes and naming conventions—all using tools that won’t cost you a dime. Whether your app is displayed on a standard monitor or a Retina display, this article ensures that your icon looks nothing short of professional. So let’s dive into the details and polish off your macOS app development project.

Prerequisites

Before diving into the process of creating an ICNS icon file for your macOS app, ensure you meet the following prerequisites:

macOS Operating System: This guide is specifically tailored for macOS, as the iconutil utility is a built-in macOS tool. Make sure you’re running macOS on your development machine.
Original high-resolution PNG icon: You should have already prepared an original, high-resolution icon file in PNG format. We’ll use this file to create the required different sizes and the ICNS icon file.
macOS Preview app: Make sure the Preview app is available on your macOS machine. You can find it by navigating to Applications → Preview, or simply by searching Preview in Spotlight (Cmd + Space).
Terminal access: You’ll need access to the macOS Terminal to run the iconutil command. You can find the Terminal app by navigating to Applications → Utilities → Terminal, or by searching for it in Spotlight (Cmd + Space).
Basic Terminal skills: Familiarity with basic Terminal commands like cd to navigate directories is beneficial, as you’ll be using Terminal to execute the iconutil command.

Once you’ve checked off these prerequisites, you’re all set to proceed with generating your ICNS icon file.

Understanding dimensions and filename conventions

The macOS operating system uses a specialized icon file format called .icns. Unlike a single image file, an .icns file is a container that holds multiple versions of the same icon, optimized for different display sizes and resolutions. macOS supports various icon sizes, and modern Macs even have Retina displays that require high-resolution icons. That’s where the @1x and @2x naming conventions come into play.

When it comes to submitting your application to the Apple App Store, there’s an additional requirement: an extra-large 1024x1024 pixel icon. This icon is crucial as it represents your app in the App Store listing and must be of the highest caliber.

You’ll need to create different sizes of the same icon in PNG format. Here’s the general list of required dimensions, expressed in pixels:

Standard resolution (@1x) icons. Simply use their dimensions.

icon_1024x1024.png (1024x1024 pixels)
icon_512x512.png (512x512 pixels)
icon_256x256.png (256x256 pixels)
icon_128x128.png (128x128 pixels)
icon_32x32.png (32x32 pixels)
icon_16x16.png (16x16 pixels)

High-resolution (@2x) icons. Double the dimensions and add the @2x suffix.

icon_1024x1024@2x.png (actually 2048x2048 pixels)
icon_512x512@2x.png (actually 1024x1024 pixels)
icon_256x256@2x.png (actually 512x512 pixels)
icon_64x64@2x.png (actually 128x128 pixels)
icon_32x32@2x.png (actually 64x64 pixels)

The @1x and @2x suffixes in the filenames indicate the display scaling factor. In short, icons without any suffix are for standard displays (@1x), and those with the @2x suffix are for Retina displays.

What is @1x? The term @1x refers to the standard resolution icons, tailored for traditional displays. These are the base versions of your app icons, without any upscaling for high-resolution displays. In the context of file naming, you don’t actually need to append the @1x suffix. The absence of a suffix implies that the icon is a standard resolution image. For instance, a standard 512x512 pixel icon would simply be named icon_512x512.png.

What is @2x? Contrastingly, @2x is used for high-resolution or Retina icons. These icons have twice the pixel density of their standard counterparts, making them suitable for Retina displays. In terms of dimensions, an @2x icon should be exactly double the size of its @1x counterpart. For example, if you have a standard icon of size 512x512 pixels, the @2x version should be 1024x1024 pixels. You would name this high-resolution icon icon_512x512@2x.png.

By preparing icons in these sizes and adhering to the proper naming conventions, you ensure that your macOS app will look crisp and clear, regardless of whether it’s viewed on a standard monitor or a Retina display. Additionally, you’ll meet all the requirements for app submission to the Apple App Store.

Let’s begin

Before you can generate an ICNS file, you need to prepare a variety of icon sizes to accommodate different display resolutions and use-cases. The macOS Preview app is a free and convenient tool to resize your original icon image into the required dimensions.

Open the original icon: Right-click on your original high-resolution icon file and select Open With → Preview.

Duplicate the file: In Preview, go to File → Duplicate to create a copy of the original icon. This ensures you keep the high-resolution file intact for future use.

Resize the image:

Go to Tools → Adjust Size.
In the pop-up window, uncheck the Resample Image box if it’s checked.
Enter the required dimensions (e.g., 512x512, 256x256, etc.) in the Width and Height fields. Make sure the pixels option is selected.
Enter 72 in the Resolution field. Make sure the pixels/inch option is selected.
Click OK.

Save the resized icon:

Go to File → Save.
Make sure to save it in PNG format.
Name the file appropriately, following the naming conventions like icon_512x512.png, icon_256x256.png, etc.

Repeat for other sizes: Repeat steps B to C for all the required icon sizes.

Organize the files: Once you have all the sizes, place them in a folder named icon.iconset.

Once you’ve prepared all your icon images and organized them into an .iconset folder, the next step is to generate the actual ICNS icon file. This is where iconutil comes in—a command-line utility built into macOS specifically for this purpose. Using iconutil is straightforward and won’t cost you anything, as it’s a built-in macOS utility.

Open Terminal app: You can find it by navigating to Applications → Utilities → Terminal, or simply by searching Terminal in Spotlight (Cmd + Space).

Navigate to the icon.iconset folder: Use the cd command to navigate to the directory where your icon.iconset folder is stored. For example:

cd /path/to/your/icon.iconset

Generate the ICNS file: Now, execute the following command to convert the icon.iconset folder with all the icon files into an ICNS file named icon.icns:

iconutil -c icns icon.iconset

Note! If the command fails, make sure you’ve navigated to the correct directory and that your icon.iconset folder contains all the required icon sizes and naming conventions.

Verify the ICNS file: A new file named icon.icns should appear in the same directory as your icon.iconset folder. Double-click it to ensure it displays correctly.

That’s it! You’ve successfully created an ICNS icon file for your macOS app. Simple, free, and effective.

Creating an ICNS file can be straightforward, but here are some tips to ensure a smooth process and professional result:

Consistency is Key: Make sure your icon design remains consistent across all sizes. A good design should be recognizable, whether it’s a 16x16 or a 1024x1024 icon.
Test on Different Displays: Always test your ICNS file on both standard and Retina displays to ensure it looks crisp and clear on all types of screens.
Use Vector Graphics: If possible, create your original design in a vector format. This will make it easier to scale your design to different sizes without losing quality.
Backup Originals: Keep a backup of your original PNG files. You may need to tweak them later, and having the originals will save you time and effort.
Check for Updates: macOS updates may introduce new icon sizes or requirements. Keep an eye on the official Apple documentation to stay up-to-date.
Use Scripting: If you find yourself creating ICNS files frequently, consider writing a shell script to automate the iconutil command, saving you time in the long run.
Resource Validation: After generating your ICNS file, validate that it meets Apple’s Human Interface Guidelines for icons. This will increase the likelihood of your app being accepted into the App Store.
Don’t Rush: Creating a compelling icon is an art. Take your time to review and adjust as necessary before finalizing your ICNS file.

Conclusion

Creating an ICNS icon file for your macOS app may appear complicated at first glance, especially with various icon sizes and naming conventions to consider. However, armed with the right knowledge and free tools, this task becomes far more manageable. By adhering to this guide, you should now have a full understanding of how to generate a polished ICNS file suitable for both standard and Retina displays—without spending a cent.

I hope this article has helped you successfully create a professional-grade ICNS icon for your macOS app. If you found this guide beneficial, feel free to leave a comment

Thank you for taking the time to read this article. May your macOS app shine brightly, distinguished by its meticulously crafted icon!

Additional resources:

Hope that Helped!

If this post helped you out and you'd like to show your support, please consider fueling future posts by buying me a coffee cup!