The First Screen a User Sees

When you distribute a macOS app yourself, the user downloads a .dmg file and double-clicks it. At that moment, a single Finder window opens. This window is the first screen where the user meets your app.

A well-made .dmg window usually looks like this — a guide image fills the background, the app icon sits on the left, and a shortcut to the Applications folder sits on the right. The user finishes the install by dragging the app icon over to Applications. This “drag to install” flow is effectively the standard installation experience for indie macOS apps.

This window doesn’t just appear on its own. You have to define the background image, the window size, and the position and size of every icon yourself. This series covers how to design that .dmg window.

This series starts from the assumption that you already have a .app that has been signed, notarized, and stapled — in other words, an app that is one step away from distribution. That process was covered in the “Distributing a macOS App Yourself” series. A .dmg is an artifact of the direct distribution (Developer ID) channel and has nothing to do with the Mac App Store channel.

What This Series Builds

Over two parts, you’ll end up with the following:

  • (Part 1, this article) The create-dmg tool + a staging folder that holds only the .app + a prepared background image
  • (Part 2) Designing the coordinates of the window, icons, and drop link + aligning the background image with those coordinates + automation

By the end of the series, you should have:

  • A staging folder that isolates and holds only the .app
  • A background image that follows the @2x Retina convention and has a normalized DPI
  • A create-dmg command in which the window size and icon positions are all set by coordinates
  • A form you can reuse as-is for every release

The Example App — FocusTimer

As in the previous series, we’ll use a fictional macOS app, FocusTimer (a simple timer app for managing focus time), as our example. FocusTimer, the paths, the coordinate values, and so on are all examples. In practice, adapt them to your own app.

What Is a DMG?

A DMG (.dmg) is a macOS disk image file. Think of it as a “virtual disk” that packs an entire folder-and-file structure inside a single file. When the user double-clicks a .dmg, macOS mounts it like a disk, and its contents open in a Finder window.

Here’s why DMGs are used for app distribution:

  • An app (.app) is actually a folder. It’s hard to put a folder directly on the internet, but wrapping it in a DMG turns it into a single file.
  • You can include a shortcut to the Applications folder inside the DMG window, guiding the user to install with a single drag.
  • You can design the look of the window — its background, icon positions, and so on — making the installation experience clean.

The Tool — create-dmg

Building a DMG by hand means going through several steps: creating an image with hdiutil, mounting it, manipulating the Finder window with AppleScript to place the icons, then unmounting it again. It’s tedious and error-prone.

create-dmg is an open-source tool that bundles this whole process into a single command. Pass it the background image, window size, and icon coordinates as options, and it produces a finished .dmg for you.

You already installed it back when setting up the prerequisite tools in Part 1 of the “Distributing a macOS App Yourself” series. If you haven’t yet, install it with Homebrew:

brew install create-dmg

There are two projects named create-dmg. The one used in this article is the command-line tool installed by Homebrew (create-dmg/create-dmg). Don’t confuse it with the separate project, which has different option names.

Step 1 — A Staging Folder That Holds Only the .app

The DMG should contain just one app icon, cleanly. But when you build and export your app, the resulting folder contains not only the .app but also byproduct files such as DistributionSummary.plist and packaging logs. If you turn that folder directly into a DMG, those byproducts end up exposed in the window too.

So you copy only the .app into an empty folder to isolate it, and then use that folder as the raw material for the DMG. This isolation folder is commonly called a staging folder.

# Copy only the .app into an empty folder so it isn't mixed with byproducts
DMG_STAGE="build/dmg-stage"
rm -rf "$DMG_STAGE"
mkdir -p "$DMG_STAGE"
cp -R "build/export/FocusTimer.app" "$DMG_STAGE/"

Now build/dmg-stage/ contains only FocusTimer.app. When you build the DMG, point create-dmg at this folder, and the window will show only the app icon, cleanly. (The Applications folder shortcut is generated automatically via a create-dmg option in Part 2.)

Step 2 — Preparing the Background Image

The heart of DMG window design is the background image. This is where people get stuck most often, so let’s go through it step by step.

Canvas Size — Why 1200×800?

In Part 2, you’ll set the DMG window size by passing --window-size 600 400 to create-dmg. Here, the unit of 600 and 400 is not pixels but points. Points are the logical coordinate unit that macOS uses.

On a Retina display, 1 point is drawn as 2 pixels. So to fill a 600×400-point window completely and sharply, the background image must be twice that size — 1200×800 pixels. This is the @2x (double-resolution) convention.

To summarize — the window is 600×400 points, and the background image is 1200×800 pixels. This 2× relationship comes back as an important factor when you set up coordinates in Part 2.

What to Draw on the Background

Here’s a common misconception worth addressing. Do not draw the app icon or the Applications folder icon into the background image. Those icons are placed onto the window as actual files by create-dmg (Part 2).

What goes into the background image is decoration and guidance elements only:

  • An arrow pointing from the app icon toward the Applications folder — the most common design for guiding the user’s eye and hand to “drag this way.”
  • If needed, a short instructional phrase such as “Drag here”
  • A brand color or a subtle background pattern

In other words, the background image is “a picture that leaves the spots where the icons will sit empty, and draws only the guide line connecting them.” You leave the two icon spots — left and right, each 100 points = 200 pixels in size (in Part 2) — empty, and place the arrow in the middle between them.

A Key Pitfall — DPI

The pitfall people fall into most with the background image is DPI (pixels per inch).

When you export a PNG from an image editor, the file stores not only the pixel count (1200×800) but also a DPI value. When Finder draws the DMG background, it looks at this DPI to back-calculate “how many points this image is.” The calculation goes roughly like this:

Point size = pixel count ÷ (DPI ÷ 72)
  • If the DPI is 144: 1200 ÷ (144 ÷ 72) = 1200 ÷ 2 = 600 points. It fills the window (600pt) exactly. ✅
  • But some image editors (e.g., Pixelmator Pro) stamp in an arbitrary DPI value (e.g., 338) on export. If the DPI is 338: 1200 ÷ (338 ÷ 72) ≈ 256 points. That’s far smaller than the window (600pt), so the background is drawn shrunk into the top-left corner of the window. ❌

The pixel count is the same 1200×800 in both cases, yet the background breaks because of one DPI value. The first time you run into this, the cause is genuinely hard to track down.

The solution is to force the exported PNG’s DPI to a uniform 144. One line with the sips command, built into macOS by default, does it:

sips -s dpiWidth 144 -s dpiHeight 144 dmg-background.png

Once you run this one line, no matter what DPI the editor stamped in, it’s set to 144, and 1200×800 pixels is interpreted as exactly 600×400 points.

The takeaway — ① make the background image 1200×800 pixels, and ② after exporting, normalize the DPI to 144 with sips. Follow these two rules and you’ll avoid the DPI pitfall.

Part 1 Wrap-Up

If you’ve followed along this far, you now have:

  • ✅ The create-dmg tool installed + an understanding of its role
  • ✅ A staging folder that isolates and holds only the .app (build/dmg-stage/)
  • ✅ A background image made at 1200×800 pixels with the DPI normalized to 144

The materials are ready. But you still don’t have a window to display the background image and place the icons in. How large to open the window, and where to place the app icon and the Applications shortcut — all of this is decided by the coordinates you pass to create-dmg.

In the next part, we’ll design those coordinates one by one, cover how to align the background’s pixel coordinates with the window’s point coordinates so that the arrow in the background image lands exactly between the two icons, and show how to automate this process so it can be reused for every release.