How to prepare a Mac app for Homebrew

The guide

A cask is a small Ruby file that tells Homebrew where to download your app, which version it is, its checksum and what to install. Casks live in a tap, which is a Git repository of casks.

1. Ship a signed and notarized build

Sign the app with your Developer ID, notarize it and staple the ticket, just as you would for a direct download. Use the notarization and signing checklist.

2. Host each version at a stable URL

Give every release its own download URL with the version in it, for example a GitHub release per version. Don't replace the file at an existing URL: the checksum in the cask would no longer match.

3. Create your own tap

A tap is a GitHub repository whose name starts with homebrew-. A repository called homebrew-tap under your account becomes the tap yourname/tap. Put casks in a Casks folder.

4. Write the cask

A minimal cask looks like this. Save it as Casks/my-app.rb:

cask "my-app" do
  version "1.2.0"
  sha256 "replace-with-the-sha256-of-your-zip"

  url "https://github.com/you/MyApp/releases/download/v#{version}/MyApp-#{version}.zip"
  name "My App"
  desc "One line about what the app does"
  homepage "https://example.com/"

  depends_on macos: ">= :sonoma"

  app "My App.app"
end

You can also add a zap stanza listing the settings files to remove when someone runs brew uninstall --zap. Homebrew's Cask Cookbook explains every stanza.

5. Add the checksum

Compute the SHA-256 of the exact file you uploaded, and paste it into the cask:

shasum -a 256 MyApp-1.2.0.zip

6. Test the install

Install from your tap on a Mac, open the app, then uninstall it:

brew install --cask yourname/tap/my-app
brew uninstall --cask my-app

7. Update the cask for every release

Change version and sha256, and push the change to your tap. Users get the new version with brew upgrade --cask.

How your users install

One command adds your tap and installs the app. Here's NotedSuite's own tap as a real example:

brew install --cask notedsuiteapps/tap/quality-noted

Homebrew docs: How to Create and Maintain a Tap · Cask Cookbook · Acceptable Casks. Requirements change, so check Homebrew's current documentation.