create-dmg: opinionated DMG packaging for macOS apps

The problem create-dmg solves for macOS app shippers

Distributing a macOS app outside the Mac App Store usually means a .dmg file. The README frames the alternatives bluntly: pay for a GUI app and customize an existing design, or run a homebrewed Bash script and still design the window yourself. create-dmg targets the second path and removes the design step. Its audience is a developer who has exported an app from Xcode and wants a disk image that opens with the app icon on one side and an Applications shortcut on the other, which is the convention Mac users already know. The README describes the tool as intentionally opinionated and simple, and states the author is not interested in adding lots of options. That sentence is the most important thing on the page. If your release process needs a specific window size, a branded background, or a multi-step installer flow, this tool is not aimed at you, and the option list confirms it.

What create-dmg actually does: appdmg, icon composition and signing

The package.json lists appdmg as a runtime dependency, so create-dmg is a front end over an existing DMG builder rather than a from-scratch implementation. The CLI takes an .app path and an optional destination directory, then produces a DMG named after the app and its version, for example Lungo 1.0.0.dmg. Two other dependencies hint at the work around that core: icns-lib handles .icns icon files and plist reads and writes property lists, which is how the app's version and bundle metadata get pulled in without the user retyping them. The repository also ships a disk-icon.icns and an assets directory, which is where the window layout and the Applications drop target come from. A separate sla.js file in the repository root corresponds to the license agreement feature documented in the README: if license.txt or license.rtf sits in the current working directory, it is attached as a software license agreement, and the image will not mount until the user agrees. The ComposeIcon directory holds a Swift package that builds a compose-icon binary, and the package.json build script compiles it for arm64 and x86_64 with xcrun swift build before copying it into the published files. That is how the DMG icon is generated from the app icon rather than shipped as a fixed image.

Installing create-dmg and building a first DMG

The README requires Node.js 20 or later, and package.json sets the same floor in its engines field. Installation is a single global npm command, which puts the create-dmg binary on your PATH.

npm install --global create-dmg

Run the help output first to confirm the binary resolved and to see the flags your installed version supports.

create-dmg --help

The help text documents the usage as create-dmg <app> [destination] with an optional output directory. The README gives two examples, one writing next to the app and one writing into a build folder.

create-dmg 'Lungo.app'
create-dmg 'Lungo.app' Build/Releases

After the command finishes you should have a file named like Lungo 1.0.0.dmg in the destination, or in the current directory when no destination is given. The README states the DMG requires macOS 10.13 or later. If you want a different title, --dmg-title takes a value of at most 27 characters and defaults to the app name. To skip signing, for example on a machine without a developer certificate, pass --no-code-sign.

create-dmg 'Lungo.app' --no-code-sign

The README notes the DMG is still created and fine even if code signing fails, and recommends --no-code-sign specifically to prevent exit code failures in CI. It also states plainly that you should not forget to notarize your DMG, linking to an external explanation rather than covering notarization itself.

Where create-dmg gets in your way

The fixed layout is the main constraint. Because the tool ships its own assets and disk-icon.icns, the visual result is the same for every app, and the README offers no flag for a custom background image or window geometry. Teams with a brand guideline that specifies the DMG background have to go back to appdmg directly, which is the dependency create-dmg wraps. Version handling is another edge: the filename embeds the version by default, and --no-version-in-filename is the escape hatch, but the README does not document how the version is read when the app bundle lacks one. The code signing path is forgiving by design, which is also a risk. A DMG that fails to sign still gets written, so a pipeline that only checks the exit code can ship an unsigned artifact unless you remove --no-code-sign and let the failure surface. Note that --no-code-sign is documented as the way to prevent exit code failures, so the two behaviours are deliberately opposite and you have to pick one. The README does not document rollback, cleanup of partial output, or what happens when the destination directory does not exist. Finally, the tool is macOS-only in practice: the README frames the workflow around Xcode exports and the DMG format itself, and nothing in the repository suggests a Windows or Linux path.

create-dmg against appdmg and the GUI route

The closest real alternative is appdmg, which create-dmg depends on. The difference in approach is configuration versus convention. appdmg takes a JSON specification describing window size, icon positions, background image, and the files to include, and it builds exactly that. create-dmg takes an .app path and decides all of those details for you, exposing only overwrite, version-in-filename, identity, dmg-title, and code-sign toggles. If you need a background image, appdmg is the layer that supports it, and you would write the spec yourself. The other alternative named in the README is a paid GUI application where you customize an existing design; that route trades a command-line flag for a mouse and a licence fee, and it does not fit an automated release. There is no online converter worth considering here, because the DMG has to be built on a Mac with the app bundle present.

Maintenance, licence and what upgrading costs

The repository is MIT licensed, which permits commercial and closed-source use, modification and redistribution provided the copyright notice and permission notice are kept. That is the standard permissive arrangement and it means you can call create-dmg from a proprietary build script without publishing anything. No legal advice here; read the license file in the repository root if the details matter to your organisation. On maintenance, the last push to the default branch was on 2026-03-21, and the most recent release, v8.1.0, is dated the same day. The releases before it are v8.0.0 on 2026-01-23 and v7.1.0 on 2025-09-09, so the cadence has been roughly one minor or major bump every few months rather than continuous churn. The practical upgrade cost is low for the CLI surface, which has stayed small, but note that v8.0.0 was a major version and package.json now requires Node.js 20 or later. If your CI image pins an older Node, a create-dmg upgrade will force a runtime upgrade with it. Dependencies such as appdmg, execa and meow are versioned with carets, so a fresh install can pull newer minor releases than a lockfile from an earlier build.

Editorial conclusion

Adopt create-dmg if you ship a macOS .app outside the Mac App Store and want the standard drag-to-Applications layout without maintaining an appdmg spec or a Bash script; the --identity and --dmg-title flags plus an optional license.txt or license.rtf in the working directory cover most release pipelines. Do not adopt it if you need a custom window size, a bespoke background image, or a Windows or Linux build host, because the README states the tool is intentionally opinionated and the repository exposes no options for those. Before wiring it into CI, verify that Node.js 20 or later is available on the runner, that the DMG opens correctly after you notarize it, and that the DMG filename matches whatever your update feed expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sindresorhus/create-dmg on GitHub