Cask Cookbook

Each cask is a Ruby block, beginning with a special header line. The cask definition itself is always enclosed in a do … end block. Example:

cask "anybar" do
  version "0.2.3"
  sha256 "c87dbc6aff5411676a471e84905d69c671b62b93b1210bd95c9d776d087de95c"

  url "https://github.com/tonsky/AnyBar/releases/download/#{version}/AnyBar-#{version}.zip"
  name "AnyBar"
  desc "Menu bar status indicator"
  homepage "https://github.com/tonsky/AnyBar"

  app "AnyBar.app"
end

The cask language is declarative

Each cask contains a series of stanzas (or “fields”) which declare how the software is to be obtained and installed. In a declarative language, the author does not need to worry about order. As long as all the needed fields are present, Homebrew determines what to do at install time.

To make maintenance easier, the most-frequently-updated stanzas are usually placed at the top. But that’s a convention, not a rule.

Exception: *_steps blocks contain an ordered sequence of constrained operations.

Header line details

The cask name (<cask-token>) on the header line cask <cask-token> do should match the cask filename, without the .rb extension, enclosed in double quotes.

The token reference describes the current naming rules and exceptions.

Stanza order

Having a common order for stanzas makes casks easier to update and parse. Below is the complete stanza sequence (no cask will have all stanzas). The empty lines shown here are also important, as they help to visually delimit information.

When multiple depends_on stanzas are present, order them alphabetically by dependency type and then value.

arch
on_arch_conditional # additional custom-defined substitutions
os
on_system_conditional # additional custom-defined substitutions

version
sha256

on_<system> # arm, intel, supported macOS releases (oldest first), macos, then linux

language

url
name
desc
homepage

livecheck

no_autobump!

deprecate!
disable!

auto_updates
conflicts_with
depends_on
container

rename

suite
app
app_image
pkg
generated_script
installer
binary
command_wrapper
manpage
bash_completion
fish_completion
zsh_completion
generate_completions_from_executable
colorpicker
dictionary
font
input_method
internet_plugin
keyboard_layout
prefpane
mdimporter
screen_saver
service
audio_unit_plugin
vst_plugin
vst3_plugin
artifact, target: # target: shown here as is required with `artifact`
stage_only

preflight_steps

postflight_steps

uninstall_preflight_steps

uninstall_postflight_steps

uninstall

zap

caveats

Note that every stanza that has additional parameters (:symbols after a ,) shall have them on separate lines, one per line. An exception is target: which typically consists of short lines.

Stanzas

Required stanzas

Each cask requires the identity and download stanzas below. Submissions to homebrew/cask may require additional stanzas such as livecheck, depends_on, uninstall or zap when the package needs them.

name multiple occurrences allowed? value
version no Application version, or the special value :latest.
sha256 no SHA-256 checksum of the file downloaded from url as calculated by the command shasum -a 256 <file>, or the special value :no_check.
url no URL to the .dmg/.zip/.tgz file (or other common archive formats) that contains the application.
name yes String providing the full and proper name defined by the vendor.
desc no One-line description of the cask. Shown when running brew info.
homepage no Application homepage; used for the brew home command.

If a homepage blocks automated requests but works in a browser, record the date it was last checked by a human:

homepage "https://www.example.com/", browsed: "2026-07-26"

This skips automated homepage availability audits for one year. Do not use a future date.

At least one artifact stanza is also required

Each cask must declare one or more artifacts (i.e. something to install). Homebrew determines a cask’s supported operating systems from its depends_on declarations, not from its artifact types. Artifact stanzas can be OS-specific or portable: app_image is Linux-only, app and pkg are macOS-only, and binary works on either operating system. Use a matching top-level depends_on :macos or depends_on :linux for a cask that supports only one operating system. Cross-platform casks should scope OS-specific artifact stanzas inside on_macos or on_linux blocks; a top-level OS dependency would drop support for the other operating system.

name multiple occurrences allowed? value
suite yes Relative path to a containing directory that should be moved into the /Applications folder on installation.
app yes Relative path to an .app that should be moved into the /Applications folder on installation.
app_image yes Relative path to an AppImage that should be linked into the configured AppImage directory on installation.
pkg yes Relative path to a .pkg file containing the distribution.
generated_script yes Generates a script for another artifact or install step to use.
installer yes Describes an executable which must be run to complete the installation.
binary yes Relative path to a Binary that should be linked into the $(brew --prefix)/bin folder on installation.
command_wrapper yes Generates a command wrapper and links it into the $(brew --prefix)/bin folder.
manpage yes Relative path to a Man Page that should be linked into the respective man page folder on installation, e.g. /opt/homebrew/share/man/man3 for my_app.3.
bash_completion yes Relative path to a Bash completion file that should be linked into the $(brew --prefix)/etc/bash_completion.d folder on installation.
fish_completion yes Relative path to a fish completion file that should be linked into the $(brew --prefix)/share/fish/vendor_completions.d folder on installation.
zsh_completion yes Relative path to a Zsh completion file that should be linked into the $(brew --prefix)/share/zsh/site-functions folder on installation.
generate_completions_from_executable yes Command and arguments used to generate shell completions from an executable at installation time.
colorpicker yes Relative path to a ColorPicker plugin that should be moved into the ~/Library/ColorPickers folder on installation.
dictionary yes Relative path to a Dictionary that should be moved into the ~/Library/Dictionaries folder on installation.
font yes Relative path to a Font that should be moved into the ~/Library/Fonts folder on installation.
input_method yes Relative path to an Input Method that should be moved into the ~/Library/Input Methods folder on installation.
internet_plugin yes Relative path to an Internet Plugin that should be moved into the ~/Library/Internet Plug-Ins folder on installation.
keyboard_layout yes Relative path to a Keyboard Layout that should be moved into the /Library/Keyboard Layouts folder on installation.
prefpane yes Relative path to a Preference Pane that should be moved into the ~/Library/PreferencePanes folder on installation.
mdimporter yes Relative path to a Spotlight Metadata Importer that should be moved into the ~/Library/Spotlight folder on installation.
screen_saver yes Relative path to a Screen Saver that should be moved into the ~/Library/Screen Savers folder on installation.
service yes Relative path to a Service that should be moved into the ~/Library/Services folder on installation.
audio_unit_plugin yes Relative path to an Audio Unit Plugin that should be moved into the ~/Library/Audio/Plug-Ins/Components folder on installation.
vst_plugin yes Relative path to a VST Plugin that should be moved into the ~/Library/Audio/Plug-Ins/VST folder on installation.
vst3_plugin yes Relative path to a VST3 Plugin that should be moved into the ~/Library/Audio/Plug-Ins/VST3 folder on installation.
artifact yes Relative path to an arbitrary path that should be moved on installation. Must provide an absolute path as a target. (Example: free-gpgmail.rb) This is only for unusual cases; the app stanza is strongly preferred when moving .app bundles.
stage_only no true. Asserts that the cask contains no activatable artifacts.

Cask artifact trust and sandboxing

Homebrew treats cask installation artifacts as trusted vendor installation actions once the cask has been accepted. Artifact stanzas such as app, pkg and installer script are expected to install software and may write outside the Caskroom through Homebrew-managed moves, macOS installer services or vendor installer code. Official macOS casks must also meet the Gatekeeper requirement; the Cask security model explains why.

Generated completion artifacts are different: generate_completions_from_executable runs an installed executable only to produce shell completion text. The complete generation operation, including writing the completion, runs in an isolated Ruby subprocess where Homebrew has an available sandbox. The sandbox allows reading the staged cask, writing the completion and temporary/cache files and blocks network access. This limits side effects from commands that should only print completion data.

On macOS, sandboxed operations can only look up explicitly allowed Mach services for directory information, power management, networking and certificates. They cannot register or launch applications through LaunchServices (including lsregister and open) or send Apple Events to other applications. These restrictions also apply to steps with network_access: true. Outbound Unix socket connections are denied except for Homebrew’s internal communication and, when network access is allowed, macOS DNS resolution. Allowing writes to a directory does not allow connections to sockets in it.

installer script: is not sandboxed. Many installer scripts are vendor installers that require broad filesystem writes, macOS services or sudo; macOS sandboxing does not work for root processes, and narrowing the write allowlist to the Caskroom plus uninstall or zap paths would break installers that legitimately write elsewhere. It would also change documented SystemCommand behaviours such as sudo:, must_succeed: and output handling.

pkg artifacts are not run in the cask sandbox either. They are installed by macOS /usr/sbin/installer, which applies package payloads, scripts and receipts according to the package metadata.

Optional stanzas

name multiple occurrences allowed? value
uninstall yes Procedures to uninstall a cask. Optional unless a pkg or installer artifact stanza is used.
conflicts_with yes List of conflicts with this cask.
caveats yes String or Ruby block providing the user with cask-specific information at install time.
livecheck no Ruby block describing how to find updates when automatic detection is insufficient. It is not used with version :latest unless the block uses skip.
depends_on yes Dependencies and operating-system or architecture requirements for this cask.
zap