# create-dmg: building a styled macOS disk image from the command line

> create-dmg is a shell script that wraps hdiutil and Finder AppleScript to produce a laid-out DMG with a background, positioned icons and an Applications drop link. It is a macOS-only packaging step, and the README is explicit about where it stops working.

**create-dmg/create-dmg** — A shell script to build fancy DMGs

- Repository: https://github.com/create-dmg/create-dmg
- Stars: 2,640 · Forks: 322
- Language: Shell
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/create-dmg-create-dmg

## The problem create-dmg solves for Mac app shippers

A DMG is not just an archive. When a user double-clicks one, Finder mounts it and shows a window, and that window is where the user decides whether the app looks finished. A plain hdiutil-created image mounts with default icon placement and no background, so the user sees a folder of files and has to work out that the .app belongs in /Applications. create-dmg exists to remove that step: it copies a source folder into a disk image, sets a volume name and icon, places a background picture, positions each icon at explicit coordinates, and can add a drop link to Applications at a chosen spot. The README describes it as "A shell script to build fancy DMGs", and that is the scope. It is for developers who already have a built .app or a staging folder and need the distribution artifact that goes on a download page. It is not a build system, not a signing tool in itself, and not cross-platform.

## How create-dmg drives hdiutil and Finder

The script is a wrapper. It reads its options, creates a writable disk image with hdiutil, mounts it, copies the contents of the source folder into it, and then runs Finder AppleScript to set the window's appearance: background image, window position and size, icon size, text size, and the coordinates of individual files. Options such as --icon "Application.app" 200 190 and --app-drop-link 600 185 are the same coordinates you would otherwise set by hand in Finder's view options. After the cosmetic pass, the script runs hdiutil again to convert the writable image into the final read-only format, UDZO by default, with UDBZ, ULFO and ULMO as alternatives via --format. The filesystem defaults to HFS+, with APFS available through --filesystem for macOS 10.13 or newer. Because the cosmetic step needs a graphical Finder session, the script offers --skip-jenkins to skip "Finder-prettifying AppleScript, useful in Sandbox and non-GUI environments", and --sandbox-safe, which the README says uses hdiutil with sandbox compatibility, does not bless, and does not execute the cosmetic AppleScript, and is not supported for APFS disk images. That last restriction is the clearest architectural boundary in the project: the pretty layout and the sandboxed path are different modes, not layers you can combine freely.

## Installing create-dmg and building a first DMG

The README lists three install routes. Homebrew is the shortest. The make install target copies the script to /usr/local/bin by default and also installs support, examples and tests under the data directory, so the prefix and bindir variables in the Makefile are the knobs if you need a different location.

```bash
brew install create-dmg
```

If you prefer building from a checkout, clone the repository and run the install target. The Makefile's prefix defaults to /usr/local and bindir to ${exec_prefix}/bin, and DESTDIR is honoured for staged installs.

```bash
git clone https://github.com/create-dmg/create-dmg.git
cd create-dmg
make install
```

The invocation pattern is the output file first, then the source folder. The README's example script deletes any previous DMG, then passes the layout options before the two positional arguments. Note that the source folder is copied wholesale into the image, so keep build artifacts and stray files out of it.

```sh
create-dmg \
  --volname "Application Installer" \
  --background "installer_background.png" \
  --window-pos 200 120 \
  --window-size 800 400 \
  --icon "Application.app" 200 190 \
  --app-drop-link 600 185 \
  "Application-Installer.dmg" \
  "source_folder/"
```

After the run you should have Application-Installer.dmg in the working directory. Mount it and the Finder window should show the background, the app icon at 200,190 and the Applications link at 600,185. The README also points to the examples folder in the source tree for further layouts.

## Encryption, codesigning and notarization are separate steps

create-dmg can encrypt the image with --encrypt (AES-256) or --encrypt-aes128, both of which prompt for a password. The README warns that the prompt arrives during the compression phase and that hdiutil will not ask a second time to confirm, so a typo produces an image nobody can open. That is a real operational hazard for a scripted release. Signing and notarization are passed through rather than implemented: --codesign takes a signature and --notarize takes keychain-stored credentials, and the README says the notarize path waits and staples, pointing to Apple's own documentation on customizing the notarization workflow. Nothing in the README suggests create-dmg manages credentials for you, so the keychain profile has to exist before the script runs. If your release pipeline expects one command to sign, notarize and staple, this is three concerns in one wrapper, and the failure messages will come from hdiutil or Apple's tooling rather than from create-dmg.

## Where create-dmg is the wrong tool

The README is unusually direct about limits. Requirements are "nothing except a standard installation of macOS/OS X", which means there is no Windows or Linux path: if you build on a Linux CI runner, you cannot produce this artifact there. macOS support is claimed back to OS X 10.6 Snow Leopard, but the README states that development and testing mostly happens in the last three to five years of releases, which as of 2026 means macOS 13 and later, and that OS X 10.5 or earlier is out of scope. So the compatibility claim and the tested range are not the same thing. Two more constraints matter. On Snow Leopard, concurrent runs may race on the same volume name because of a Finder bug, so parallel builds on that version are unsafe. And --bless is deprecated and needs macOS 12.2.1 or older, so any workflow built around blessing the mount folder is on a version ceiling. There is also a timing workaround: --applescript-sleep-duration sets the sleep before the AppleScript runs, defaulting to 5 seconds, to work around occasional "Can't get disk" (-1728) errors. A default sleep in a release script is a sign that the Finder automation is not fully deterministic, and adding seconds to every build is the price.

## Alternatives: dmgbuild and node-appdmg

The README names two alternatives, and the difference is the approach rather than the output. node-appdmg is a Node.js tool, so it brings a JavaScript runtime and a package.json into the release process; that suits teams already building macOS artifacts with Node tooling, and it is a poor fit if you want the packaging step to depend on nothing but the system. dmgbuild is a Python package, installed from PyPI, and it configures the image through a settings file rather than a long argument list, which is easier to keep under version control and diff when a layout changes. create-dmg sits at the other end: a single shell script with no runtime dependency beyond macOS itself, configured entirely by command-line flags, with the layout living in the invocation. That is convenient for a one-off or a small script and less convenient when the layout grows, because a long create-dmg call is harder to review than a settings file. If you want a declarative layout or you are already in Python or Node, the alternatives are worth the extra dependency.

## Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-07-02, which is the same date as the v1.3.0 release. The release history shows v1.2.2 in May 2024, v1.2.3 in November 2025 and v1.3.0 in July 2026, so the cadence is irregular rather than frequent. The README describes the project as "mostly maintained by @aonez and the contributors who send pull requests" and states a merge policy: any pull request that adds something useful and does not break existing things will be merged. That is a low-friction policy, and it also means the maintainers are not promising a roadmap. Upgrading is cheap in the installed case, because make install overwrites a single script in bindir and refreshes the support, examples and tests directories under the data directory; make uninstall removes the script and that data directory. There is no service to restart and no database migration. The licence is MIT, which is permissive and imposes no copyleft obligation on your own code, but the script shells out to hdiutil and Apple's codesign and notarization tooling, so your distribution still has to satisfy Apple's requirements. That is a packaging question, not a licence question, and it is worth checking with whoever handles your releases rather than treating the MIT licence as the whole story.

## Conclusion

Use create-dmg if you ship a macOS app and want the drag-to-Applications layout produced by a script you can run in CI on a Mac runner, with --skip-jenkins or --sandbox-safe when there is no Finder. Do not use it if you need to build a DMG on Windows or Linux, if you target OS X 10.5 or earlier, or if you need APFS images together with sandbox-safe mode. Before adopting it, verify that your macOS version is in the 13-and-later range the README says development and testing covers, and check whether your release process depends on --bless, which the README marks deprecated and requires macOS 12.2.1 or older.

## FAQ

### What is a DMG on a Mac, and what does create-dmg add to it?

A DMG is a macOS disk image that mounts as a volume when opened. create-dmg builds one from a source folder and adds the Finder layout: volume name and icon, background image, window position and size, icon positions and an Applications drop link.

### Which macOS tool allows users to create .DMG files?

On macOS the underlying tool is hdiutil, and create-dmg is a shell script that drives it along with Finder AppleScript for the cosmetic layout. The README requires nothing beyond a standard macOS installation.

### Can I convert an exe to DMG with create-dmg?

No. create-dmg copies the contents of a source folder into a macOS disk image, and the README requires a standard installation of macOS/OS X; there is no documented path for converting a Windows executable.

### Is there a macOS DMG installer available for create-dmg?

The README offers three installation routes: brew install create-dmg, downloading the latest release and running make install, or cloning the repository and running the script from there. It does not describe a packaged .dmg installer for the tool itself.

## Sources

- [create-dmg/create-dmg on GitHub](https://github.com/create-dmg/create-dmg)
- [Issues](https://github.com/create-dmg/create-dmg/issues)
- [License: MIT](https://github.com/create-dmg/create-dmg/blob/master/LICENSE)
- [README](https://github.com/create-dmg/create-dmg/blob/master/README.md)
- [Releases](https://github.com/create-dmg/create-dmg/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/create-dmg-create-dmg