nix-darwin Configuration Options

Additional arguments passed to each module in addition to ones like lib, config, and pkgs, modulesPath.

This option is also available to all submodules. Submodules do not inherit args from their parent module, nor do they provide args to their parent module or sibling submodules. The sole exception to this is the argument name which is provided by parent modules to a submodule and contains the attribute name the submodule is bound to, or a unique generated name if it is not bound to an attribute.

Some arguments are already passed by default, of which the following cannot be changed with this option:

For NixOS, the default value for this option includes at least this argument:

Type: lazy attribute set of raw value

Default:

{ }

Declared by:

Whether to install documentation of packages from environment.systemPackages into the generated system path.

See “Multiple-output packages” chapter in the nixpkgs manual for more info.

Type: boolean

Default:

true

Declared by:

Whether to install documentation distributed in packages’ /share/doc. Usually plain text and/or HTML. This also includes “doc” outputs.

Type: boolean

Default:

true

Declared by:

Whether to install info pages and the info command. This also includes “info” outputs.

Type: boolean

Default:

true

Declared by:

Whether to install manual pages and the man command. This also includes “man” outputs.

Type: boolean

Default:

true

Declared by:

Whether to install all terminfo outputs

Type: boolean

Default:

false

Declared by:

The path of the darwin configuration.nix used to configure the system, this updates the default darwin-config entry in NIX_PATH. Since this changes an environment variable it will only apply to new shells.

NOTE: Changing this requires running darwin-rebuild switch -I darwin-config=/path/to/configuration.nix the first time to make darwin-rebuild aware of the custom location.

Type: null or absolute path or string

Default:

if config.nixpkgs.flake.setNixPath then
  # Don’t set this for flake‐based systems.
  null
else if config.system.stateVersion >= 6 then
  "/etc/nix-darwin/configuration.nix"
else
  "${config.system.primaryUserHome}/.nixpkgs/darwin-configuration.nix"

Declared by:

Set of default packages that aren’t strictly necessary for a running system, entries can be removed for a more minimal NixOS installation.

Like with systemPackages, packages are installed to /run/current-system/sw. They are automatically available to all users, and are automatically updated every time you rebuild the system configuration.

Type: list of package

Default: these packages, with their meta.priority numerically increased (thus lowering their installation priority):

[  ]

Example:

[ ]

Declared by:

Set of files that have to be linked in /etc.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Whether this file should be generated. This option allows specific files to be disabled.

Type: boolean

Default:

true

Declared by:

Path of the source file.

Type: absolute path

Declared by:

Name of symlink. Defaults to the attribute name.

Type: string

Default:

"‹name›"

Declared by:

Text of the file.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Shell script code called during global environment initialisation after all variables and profileVariables have been set. This code is assumed to be shell-independent, which means you should stick to pure sh without sh word split.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Entries listed here will be appended to the meta.outputsToInstall attribute for each package in environment.systemPackages, and the files from the corresponding derivation outputs symlinked into /run/current-system/sw.

For example, this can be used to install the dev and info outputs for all packages in the system environment, if they are available.

To use specific outputs instead of configuring them globally, select the corresponding attribute on the package derivation, e.g. libxml2.dev or coreutils.info.

Type: list of string

Default:

[ ]

Example:

[
  "dev"
  "info"
]

Declared by:

Shell fragments to be run after the system environment has been created. This should only be used for things that need to modify the internals of the environment, e.g. generating MIME caches. The environment being built can be accessed at $out.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Shell script code called during interactive shell initialisation. This code is asumed to be shell-independent, which means you should stick to pure sh without sh word split.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Set of files that have to be linked in /Library/LaunchAgents.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Whether this file should be generated. This option allows specific files to be disabled.

Type: boolean

Default:

true

Declared by:

Path of the source file.

Type: absolute path

Declared by:

Name of symlink. Defaults to the attribute name.

Type: string

Default:

"‹name›"

Declared by:

Text of the file.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Set of files that have to be linked in /Library/LaunchDaemons.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Whether this file should be generated. This option allows specific files to be disabled.

Type: boolean

Default:

true

Declared by:

Path of the source file.

Type: absolute path

Declared by:

Name of symlink. Defaults to the attribute name.

Type: string

Default:

"‹name›"

Declared by:

Text of the file.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Shell script code called during login shell initialisation. This code is asumed to be shell-independent, which means you should stick to pure sh without sh word split.

Type: strings concatenated with “\n”

Default:

""

Declared by:

List of directories to be symlinked in /run/current-system/sw.

Type: list of string

Default:

[ ]

Example:

[
  "/share/doc"
]

Declared by:

A list of profiles used to setup the global environment.

Type: list of string

Default:

[ ]

Declared by:

An attribute set that maps aliases (the top level attribute names in this option) to command strings or directly to build outputs. The alises are added to all users’ shells.

Type: attribute set of string

Default:

{ }

Example:

{
  ll = "ls -l";
}

Declared by:

Shell script code called during shell initialisation. This code is asumed to be shell-independent, which means you should stick to pure sh without sh word split.

Type: strings concatenated with “\n”

Default:

""

Declared by:

A list of permissible login shells for user accounts.

The default macOS shells will be automatically included:

Type: list of (package or absolute path)

Default:

[ ]

Example:

[ pkgs.bashInteractive pkgs.zsh ]

Declared by:

The set of packages that appear in /run/current-system/sw. These packages are automatically available to all users, and are automatically updated every time you rebuild the system configuration. (The latter is the main difference with installing them in the default profile, /nix/var/nix/profiles/default.

Type: list of package

Default:

[ ]

Example:

[ pkgs.firefox pkgs.thunderbird ]

Declared by:

The set of paths that are added to PATH.

Type: list of (absolute path or string)

Default:

[ ]

Declared by:

Set of files that have to be linked in ~/Library/LaunchAgents.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Whether this file should be generated. This option allows specific files to be disabled.

Type: boolean

Default:

true

Declared by:

Path of the source file.

Type: absolute path

Declared by:

Name of symlink. Defaults to the attribute name.

Type: string

Default:

"‹name›"

Declared by:

Text of the file.

Type: strings concatenated with “\n”

Default:

""

Declared by:

A set of environment variables used in the global environment. These variables will be set on shell initialisation. The value of each variable can be either a string or a list of strings. The latter is concatenated, interspersed with colon characters.

Type: attribute set of (string or list of string)

Default:

{ }

Example:

{
  EDITOR = "vim";
  LANG = "nl_NL.UTF-8";
}

Declared by:

List of fonts to install into /Library/Fonts/Nix Fonts.

Type: list of absolute path

Default:

[ ]

Example:

[ pkgs.dejavu_fonts ]

Declared by:

Whether to enable nix-darwin to manage installing/updating/upgrading Homebrew taps, formulae, casks, Mac App Store apps, Visual Studio Code extensions, Go packages, and Cargo crates using Homebrew Bundle.

Note that enabling this option does not install Homebrew, see the Homebrew website for installation instructions.

Use the homebrew.brews, homebrew.casks, homebrew.masApps, homebrew.vscode, homebrew.goPackages, and homebrew.cargoPackages options to list the Homebrew formulae, casks, Mac App Store apps, Visual Studio Code extensions, Go packages, and Cargo crates you’d like to install. Use the homebrew.taps option, to make additional formula repositories available to Homebrew. This module uses those options (along with the homebrew.caskArgs options) to generate a Brewfile that nix-darwin passes to the brew bundle command during system activation.

The default configuration of this module prevents Homebrew Bundle from auto-updating Homebrew and all formulae, as well as upgrading anything that’s already installed, so that repeated invocations of darwin-rebuild switch (without any change to the configuration) are idempotent. You can modify this behavior using the options under homebrew.onActivation.

This module also provides a few options for modifying how Homebrew commands behave when you manually invoke them, under homebrew.global.

Type: boolean

Default:

false

Example:

true

Declared by:

Whether to enable Homebrew Bash shell integration, which sets up Homebrew’s environment and shell completions .

Type: boolean

Default:

false

Example:

true

Declared by:

Whether to enable Homebrew Fish shell integration, which sets up Homebrew’s environment and shell completions .

Type: boolean

Default:

false

Example:

true

Declared by:

Whether to enable Homebrew Zsh shell integration, which sets up Homebrew’s environment and shell completions .

Type: boolean

Default:

false

Example:

true

Declared by:

List of Homebrew formulae to install.

Formulae defined as strings, e.g., "imagemagick", are a shorthand for:

{ name = "imagemagick"; }

Type: list of ((submodule) or string convertible to it)

Default:

[ ]

Example:

# Adapted from https://docs.brew.sh/Brew-Bundle-and-Brewfile
[
  # `brew install`
  "imagemagick"

  # `brew install --with-rmtp`, `brew services restart` on version changes
  {
    name = "denji/nginx/nginx-full";
    args = [ "with-rmtp" ];
    restart_service = "changed";
  }

  # `brew install`, always `brew services restart`, `brew link`, `brew unlink mysql` (if it is installed)
  {
    name = "mysql@5.6";
    restart_service = true;
    link = true;
    conflicts_with = [ "mysql" ];
  }

  # `brew install`, run a post-install command on version changes
  {
    name = "postgresql@16";
    postinstall = "\${HOMEBREW_PREFIX}/opt/postgresql@16/bin/postgres -D \${HOMEBREW_PREFIX}/var/postgresql@16";
  }
]

Declared by:

Argument flags to pass to brew install. Values should not include the leading "--".

Type: null or (list of string)

Default:

null

Declared by:

List of formulae that should be unlinked and their services stopped (if they are installed).

Type: null or (list of string)

Default:

null

Declared by:

Whether to link the formula to the Homebrew prefix. When set to "overwrite", existing symlinks will be overwritten (brew link --overwrite). When this option is null, Homebrew will use its default behavior, which is to link the formula if it’s currently unlinked and not keg-only, and to unlink the formula if it’s currently linked and keg-only.

Type: null or boolean or value “overwrite” (singular enum)

Default:

null

Declared by:

The name of the formula to install.

Type: string

Declared by:

A shell command to run after the formula is installed or upgraded. The command is passed to the system shell and only executes when the formula actually changed (was freshly installed or upgraded), not on every brew bundle run.

Type: null or string

Default:

null

Declared by:

Whether to run brew services restart for the formula and register it to launch at login (or boot). If set to "changed", the service will only be restarted when the formula is newly installed or upgraded. If set to "always", the service will be restarted on every brew bundle run, even if nothing changed.

Homebrew’s default is false.

Type: null or boolean or one of “changed”, “always”

Default:

null

Declared by:

Whether to run brew services start for the formula and register it to launch at login (or boot). Unlike restart_service, this only starts the service if it is not currently running, without restarting an already-running service.

Homebrew’s default is false.

Type: null or boolean

Default:

null

Declared by:

Whether to trust this formula during nix-darwin system activation, by adding the trusted: true option to its brew bundle Brewfile entry.

Homebrew 6.0.0 enabled HOMEBREW_REQUIRE_TAP_TRUST by default, which refuses to load formulae from non-official taps that haven’t been trusted, aborting activation. Set this to true for a formula from a non-official tap you control so it is installed during activation.

This only takes effect when name is a fully-qualified name (user/repo/formula), since only fully-qualified names map to a tap and can be trusted (and installed) on their own. When name is a plain formula name, it is resolved through your tapped repositories, so trust must instead come from the containing tap being marked as trusted (see homebrew.taps). Official taps are always trusted, so this has no effect on them.

Type: boolean

Default:

true

Example:

false

Declared by:

List of Rust packages to install using cargo install.

Homebrew will automatically install the rust formula if it is not already installed.

Type: list of string

Default:

[ ]

Example:

[
  "ripgrep"
]

Declared by:

Arguments passed to brew install --cask for all casks listed in homebrew.casks.

Type: submodule

Default:

{ }

Example:

{
  appdir = "~/Applications";
  require_sha = true;
}

Declared by:

Target location for Applications.

Homebrew’s default is /Applications.

Type: null or string

Default:

null

Declared by:

Target location for Audio Unit Plugins.

Homebrew’s default is ~/Library/Audio/Plug-Ins/Components.

Type: null or string

Default:

null

Declared by:

Target location for Color Pickers.

Homebrew’s default is ~/Library/ColorPickers.

Type: null or string

Default:

null

Declared by:

Target location for Dictionaries.

Homebrew’s default is ~/Library/Dictionaries.

Type: null or string

Default:

null

Declared by:

Target location for Fonts.

Homebrew’s default is ~/Library/Fonts.

Type: null or string

Default:

null

Declared by:

Whether to ignore cask dependencies, e.g., when you manage them externally.

Homebrew’s default is false.

Type: null or boolean

Default:

null

Declared by:

Target location for Input Methods.

Homebrew’s default is ~/Library/Input Methods.

Type: null or string

Default:

null

Declared by:

Target location for Internet Plugins.

Homebrew’s default is ~/Library/Internet Plug-Ins.

Type: null or string

Default:

null

Declared by:

Comma-separated list of language codes to prefer for cask installation. The first matching language is used, otherwise it reverts to the cask’s default language. The default value is the language of your system.

Type: null or string

Default:

null

Example:

"zh-TW"

Declared by:

Target location for Spotlight Plugins.

Homebrew’s default is ~/Library/Spotlight.

Type: null or string

Default:

null

Declared by:

Whether to disable linking of helper executables.

Homebrew’s default is false.

Type: null or boolean

Default:

null

Declared by:

Whether to disable quarantining of downloads.

Note: this option is deprecated in Homebrew and may be removed in a future release. See Homebrew/brew#20755.

Homebrew’s default is false.

Type: null or boolean

Default:

null

Declared by:

Target location for Preference Panes.

Homebrew’s default is ~/Library/PreferencePanes.

Type: null or string

Default:

null

Declared by:

Target location for QuickLook Plugins.

Homebrew’s default is ~/Library/QuickLook.

Type: null or string

Default:

null

Declared by:

Whether to require casks to have a checksum.

Homebrew’s default is false.

Type: null or boolean

Default:

null

Declared by:

Target location for Screen Savers.

Homebrew’s default is ~/Library/Screen Savers.

Type: null or string

Default:

null

Declared by:

Target location for Services.

Homebrew’s default is ~/Library/Services.

Type: null or string

Default:

null

Declared by:

Target location for VST3 Plugins.

Homebrew’s default is ~/Library/Audio/Plug-Ins/VST3.

Type: null or string

Default:

null

Declared by:

Target location for VST Plugins.

Homebrew’s default is ~/Library/Audio/Plug-Ins/VST.

Type: null or string

Default:

null

Declared by:

List of Homebrew casks to install.

Casks defined as strings, e.g., "google-chrome", are a shorthand for:

{ name = "google-chrome"; }

Type: list of ((submodule) or string convertible to it)

Default:

[ ]

Example:

# Adapted from https://docs.brew.sh/Brew-Bundle-and-Brewfile
[
  # `brew install --cask`
  "google-chrome"

  # `brew install --cask --appdir=~/my-apps/Applications`
  {
    name = "firefox";
    args = { appdir = "~/my-apps/Applications"; };
  }

  # always upgrade auto-updated or unversioned cask to latest version even if already installed
  {
    name = "opera";
    greedy = true;
  }

  # `brew install --cask`, run a post-install command on install or upgrade
  {
    name = "google-cloud-sdk";
    postinstall = "\${HOMEBREW_PREFIX}/bin/gcloud components update";
  }
]

Declared by:

Arguments passed to brew install --cask when installing this cask. See homebrew.caskArgs for the available options.

Type: null or (submodule)

Default:

null

Declared by:

Whether to always upgrade this cask regardless of whether it’s unversioned or it updates itself.

Type: null or boolean

Default:

null

Declared by:

The name of the cask to install.

Type: string

Declared by:

A shell command to run after the cask is installed or upgraded. The command is passed to the system shell and only executes when the cask was actually installed or upgraded, not on every brew bundle run.

Type: null or string

Default:

null

Declared by:

Whether to trust this cask during nix-darwin system activation, by adding the trusted: true option to its brew bundle Brewfile entry.

Homebrew 6.0.0 enabled HOMEBREW_REQUIRE_TAP_TRUST by default, which refuses to load casks from non-official taps that haven’t been trusted, silently skipping them. Set this to true for a cask from a non-official tap you control so it is installed during activation.

This only takes effect when name is a fully-qualified name (user/repo/cask), since only fully-qualified names map to a tap and can be trusted (and installed) on their own. When name is a plain cask name, it is resolved through your tapped repositories, so trust must instead come from the containing tap being marked as trusted (see homebrew.taps). Official taps are always trusted, so this has no effect on them.

Type: boolean

Default:

true

Example:

false

Declared by:

Extra lines to be added verbatim to the bottom of the generated Brewfile.

Type: strings concatenated with “\n”

Default:

""

Example:

''
  # 'brew cask install' only if '/usr/libexec/java_home --failfast' fails
  cask "java" unless system "/usr/libexec/java_home --failfast"
''

Declared by:

Options for configuring the behavior of Homebrew commands when you manually invoke them.

Type: submodule

Default:

{ }

Declared by:

Whether to enable Homebrew to auto-update itself and all formulae when you manually invoke commands like brew install, brew upgrade, brew tap, and brew bundle [install].

Note that Homebrew auto-updates when you manually invoke commands like the ones mentioned above if it’s been more than 5 minutes since it last updated.

You may want to consider disabling this option if you have homebrew.onActivation.upgrade enabled, and homebrew.onActivation.autoUpdate disabled, if you want to ensure that your installed formulae will only be upgraded during nix-darwin system activation, after you’ve explicitly run brew update.

Implementation note: when disabled, this option sets the HOMEBREW_NO_AUTO_UPDATE environment variable, by adding it to environment.variables.

Type: boolean

Default:

true

Declared by:

Whether to enable Homebrew to automatically use the Brewfile that this module generates in the Nix store, when you manually invoke brew bundle.

Implementation note: when enabled, this option sets the HOMEBREW_BUNDLE_FILE environment variable to the path of the Brewfile that this module generates in the Nix store, by adding it to environment.variables.

Type: boolean

Default:

false

Declared by:

List of Go packages to install using go install.

Homebrew will automatically install the go formula if it is not already installed.

Type: list of string

Default:

[ ]

Example:

[
  "github.com/charmbracelet/crush"
]

Declared by:

Whether to always upgrade casks listed in homebrew.casks regardless of whether it’s unversioned or it updates itself.

Homebrew’s default is false.

Type: null or boolean

Default:

null

Declared by:

Applications to install from Mac App Store using mas.

Note that you need to be signed into the Mac App Store for mas to successfully install and upgrade applications, and that unfortunately apps removed from this option will not be uninstalled automatically even if homebrew.onActivation.cleanup is set to "uninstall" or "zap" (this is currently a limitation of Homebrew Bundle).

For more information on mas see: github.com/mas-cli/mas.

Type: attribute set of (positive integer, meaning >0)

Default:

{ }

Example:

{
  "1Password for Safari" = 1569813296;
  Xcode = 497799835;
}

Declared by:

Options for configuring the behavior of the brew bundle command that nix-darwin runs during system activation.

Type: submodule

Default:

{ }

Declared by:

Whether to enable Homebrew to auto-update itself and all formulae during nix-darwin system activation. The default is false so that repeated invocations of darwin-rebuild switch are idempotent.

Note that Homebrew auto-updates when it’s been more than 5 minutes since it last updated.

Although auto-updating is disabled by default during system activation, note that Homebrew will auto-update when you manually invoke certain Homebrew commands. To modify this behavior see homebrew.global.autoUpdate.

Implementation note: when disabled, this option sets the HOMEBREW_NO_AUTO_UPDATE environment variable when nix-darwin invokes brew bundle [install] during system activation.

Type: boolean

Default:

false

Declared by:

This option manages what happens to packages installed by Homebrew that aren’t present in the Brewfile generated by this module, during nix-darwin system activation.

When set to "none" (the default), packages not present in the generated Brewfile are left installed.

When set to "check", nix-darwin verifies during system activation that no Homebrew packages (taps, formulae, casks, etc.) are installed that aren’t present in the generated Brewfile. If extra packages are found, activation fails with a list of them. Note that when this check fails during darwin-rebuild switch, the entire system activation is aborted and no other configuration changes will be applied until the issue is resolved.

When set to "uninstall", nix-darwin invokes brew bundle [install] with the --cleanup flag. This uninstalls all packages not listed in the generated Brewfile, i.e., brew uninstall is run for those packages.

When set to "zap", nix-darwin invokes brew bundle [install] with the --cleanup --zap flags. This uninstalls all packages not listed in the generated Brewfile, and if the package is a cask, removes all files associated with that cask. In other words, brew uninstall --zap is run for all those packages.

If you plan on exclusively using nix-darwin to manage packages installed by Homebrew, you probably want to set this option to "uninstall" or "zap".

Type: one of “none”, “check”, “uninstall”, “zap”

Default:

"none"

Example:

"uninstall"

Declared by:

Extra environment variables to set when nix-darwin invokes brew bundle [install] during system checks and activation.

Useful for setting Homebrew’s HOMEBREW_NO_* variables (e.g., HOMEBREW_NO_ENV_HINTS, HOMEBREW_NO_ANALYTICS, HOMEBREW_NO_UPDATE_REPORT_NEW) that aren’t inherited from the user’s shell environment because activation runs under sudo.

Each entry is prepended to the brew bundle invocation in the form KEY=VALUE, alongside HOMEBREW_NO_AUTO_UPDATE=1 when applicable.

Type: attribute set of string

Default:

{ }

Example:

{
  HOMEBREW_NO_ANALYTICS = "1";
  HOMEBREW_NO_ENV_HINTS = "1";
}

Declared by:

Extra flags to pass to brew bundle [install] during nix-darwin system activation.

Type: list of string

Default:

[ ]

Example:

[
  "--verbose"
]

Declared by:

Whether to enable Homebrew to upgrade outdated formulae and Mac App Store apps during nix-darwin system activation. The default is false so that repeated invocations of darwin-rebuild switch are idempotent.

Implementation note: when disabled, nix-darwin invokes brew bundle [install] with the --no-upgrade flag during system activation.

Type: boolean

Default:

false

Declared by:

The Homebrew prefix directory, i.e., the value that brew --prefix returns. The default is automatically set based on your system’s platform, and should only need to be changed if you manually installed Homebrew in a non-standard location.

Type: string

Default:

if pkgs.stdenv.hostPlatform.isAarch64 then "/opt/homebrew"
else "/usr/local"

Declared by:

List of Homebrew formula repositories to tap.

Taps defined as strings, e.g., "user/repo", are a shorthand for:

{ name = "user/repo"; }

Type: list of ((submodule) or string convertible to it)

Default:

[ ]

Example:

# Adapted from https://docs.brew.sh/Brew-Bundle-and-Brewfile
[
  # `brew tap`
  "apple/apple"

  # `brew tap` with custom Git URL and arguments
  {
    name = "user/tap-repo";
    clone_target = "https://user@bitbucket.org/user/homebrew-tap-repo.git";
    force_auto_update = true;
  }
]

Declared by:

Use this option to tap a formula repository from anywhere, using any transport protocol that git handles. When clone_target is specified, taps can be cloned from places other than GitHub and using protocols other than HTTPS, e.g., SSH, git, HTTP, FTP(S), rsync.

Type: null or string

Default:

null

Declared by:

Whether to auto-update the tap even if it is not hosted on GitHub. By default, only taps hosted on GitHub are auto-updated (for performance reasons).

Note: Homebrew Bundle accepts this option in Brewfile syntax but may silently ignore it during installation. See the Homebrew Bundle source for current behavior.

Type: null or boolean

Default:

null

Declared by:

When clone_target is unspecified, this is the name of a formula repository to tap from GitHub using HTTPS. For example, "user/repo" will tap https://github.com/user/homebrew-repo.

Type: string

Example:

"apple/apple"

Declared by:

Whether to trust this tap during nix-darwin system activation, by adding the trusted: true option to its brew bundle Brewfile entry.

Homebrew 6.0.0 enabled HOMEBREW_REQUIRE_TAP_TRUST by default, which refuses to load formulae/casks from non-official taps that haven’t been trusted, aborting activation. Set this to true for non-official taps you control so their formulae and casks are installed during activation. Official taps are always trusted, so this has no effect only them.

Type: boolean

Default:

false

Example:

true

Declared by:

The user that owns the Homebrew installation. In most cases this should be the normal user account that you installed Homebrew as.

Type: string

Default:

config.system.primaryUser

Declared by:

List of Visual Studio Code extensions to install using Homebrew Bundle.

A compatible editor (Visual Studio Code, VSCodium, Cursor, or VS Code Insiders) must be available. If none is found, Homebrew will attempt to install visual-studio-code automatically.

For more information on code see: VSCode Extension Marketplace.

Type: list of string

Default:

[ ]

Example:

[
  "golang.go"
]

Declared by:

Definition of per-user launchd agents.

When a user logs in, a per-user launchd is started. It does the following:

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Command executed as the service’s main process.

Type: string or absolute path

Default:

""

Declared by:

Environment variables passed to the service’s processes.

Type: attribute set of (string or list of string)

Default:

{ }

Example:

{
  LANG = "nl_NL.UTF-8";
  PATH = "/foo/bar/bin";
}

Declared by:

Packages added to the service’s PATH environment variable. Only the bin and subdirectories of each package is added.

Type: list of (absolute path or string)

Default:

[ ]

Declared by:

Shell commands executed as the service’s main process.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Each attribute in this set specifies an option for a key in the plist. https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man5/launchd.plist.5.html

Type: submodule

Default:

{ }

Example:

{
  KeepAlive = true;
  Program = "/run/current-system/sw/bin/nix-daemon";
}

Declared by:

When a job dies, launchd kills any remaining processes with the same process group ID as the job. Setting this key to true disables that behavior.

Type: null or boolean

Default:

null

Declared by:

This optional key specifies that launchd should adjust its log mask temporarily to LOG_DEBUG while dealing with this job.

Type: null or boolean

Default:

null

Declared by:

This optional key is used as a hint to launchctl(1) that it should not submit this job to launchd when loading a job or jobs. The value of this key does NOT reflect the current state of the job on the running system. If you wish to know whether a job is loaded in launchd, reading this key from a configuration file yourself is not a sufficient test. You should query launchd for the presence of the job using the launchctl(1) list subcommand or use the ServiceManagement framework’s SMJobCopyDictionary() method.

Note that as of Mac OS X v10.6, this key’s value in a configuration file conveys a default value, which is changed with the [-w] option of the launchctl(1) load and unload subcommands. These subcommands no longer modify the configuration file, so the value displayed in the configuration file is not necessarily the value that launchctl(1) will apply. See launchctl(1) for more information.

Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria are insufficient to describe the conditions under which your job needs to run. The cost to have a job loaded in launchd is negligible, so there is no harm in loading a job which only runs once or very rarely.

Type: null or boolean

Default:

null

Declared by:

This flag causes launchd to use the glob(3) mechanism to update the program arguments before invocation.

Type: null or boolean

Default:

null

Declared by:

This flag instructs launchd that the job promises to use vproc_transaction_begin(3) and vproc_transaction_end(3) to track outstanding transactions that need to be reconciled before the process can safely terminate. If no outstanding transactions are in progress, then launchd is free to send the SIGKILL signal.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to specify additional environment variables to be set before running the job.

Type: null or (attribute set of string)

Default:

null

Declared by:

The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The value zero is interpreted as infinity.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies the group to run the job as. This key is only applicable when launchd is running as root. If UserName is set and GroupName is not, the the group will be set to the default group of the user.

Type: null or string

Default:

null

Declared by:

Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following keys apply:

Type: null or (submodule)

Default:

null

Example:

{
  NumberOfFiles = 4096;
}

Declared by:

The maximum amount of cpu time (in seconds) to be used by each process.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) core file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the sbrk(2) system call.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of open files for this process. Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) to which a process’s resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the stack segment for a process; this defines how far a program’s stack segment may be extended. Stack extension is performed automatically by the system.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies whether initgroups(3) should be called before running the job. The default is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to control whether your job is to be kept continuously running or to let demand and conditions control the invocation. The default is false and therefore only demand will start the job. The value may be set to true to unconditionally keep the job alive. Alternatively, a dictionary of conditions may be specified to selectively control whether launchd keeps a job alive or not. If multiple keys are provided, launchd ORs them, thus providing maximum flexibility to the job to refine the logic and stall if necessary. If launchd finds no reason to restart the job, it falls back on demand based invocation. Jobs that exit quickly and frequently when configured to be kept alive will be throttled to converve system resources.

Type: null or boolean or (submodule)

Default:

null

Declared by:

This required key uniquely identifies the job to launchd.

Type: string

Declared by:

Specifies higher-level event types to be used as launch-on-demand event sources. Each sub-dictionary defines events for a particular event subsystem, such as “com.apple.iokit.matching”, which can be used to launch jobs based on the appearance of nodes in the IORegistry. Each dictionary within the sub-dictionary specifies an event descriptor that is specified to each event subsystem. With this key, the job promises to use the xpc_set_event_stream_handler(3) API to consume events. See xpc_events(3) for more details on event sources.

Type: null or (attribute set)

Default:

null

Example:

{
  "com.apple.iokit.matching" = {
    "com.apple.usb.device" = {
      IOMatchLaunchStream = true;
      IOProviderClass = "IOUSBDevice";
      idProduct = "*";
      idVendor = "*";
    };
  };
}

Declared by:

This optional key specifies whether the job can only be run once and only once. In other words, if the job cannot be safely respawned without a full machine reboot, then set this key to be true.

Type: null or boolean

Default:

null

Declared by:

This configuration file only applies to hosts NOT listed with this key. Note: One should set kern.hostname in sysctl.conf(5) for this feature to work reliably.

Type: null or (list of string)

Default:

null

Declared by:

This configuration file only applies to the hosts listed with this key. Note: One should set kern.hostname in sysctl.conf(5) for this feature to work reliably.

Type: null or (list of string)

Default:

null

Declared by:

This configuration file only applies to sessions of the type specified. This key is used in concert with the -S flag to launchctl.

Type: null or string or list of string

Default:

null

Declared by:

This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O when the process is throttled with the Darwin-background classification.

Type: null or boolean

Default:

null

Declared by:

This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to specify Mach services to be registered with the Mach bootstrap sub-system. Each key in this dictionary should be the name of service to be advertised. The value of the key must be a boolean and set to true. Alternatively, a dictionary can be used instead of a simple true value.

Finally, for the job itself, the values will be replaced with Mach ports at the time of check-in with launchd.

Type: null or (attribute set of (boolean or (submodule)))

Default:

null

Example:

{
  "org.nixos.service" = {
    ResetAtClose = true;
  };
}

Declared by:

This optional key specifies what nice(3) value should be applied to the daemon.

Type: null or signed integer

Default:

null

Declared by:

This key was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was true. This key has been deprecated and replaced in Mac OS X 10.5 and later with the more powerful KeepAlive option.

Type: null or boolean

Default:

null

Declared by:

This optional key describes, at a high level, the intended purpose of the job. The system will apply resource limits based on what kind of job it is. If left unspecified, the system will apply light resource limits to the job, throttling its CPU usage and I/O bandwidth. The following are valid values:

Type: null or one of “Background”, “Standard”, “Adaptive”, “Interactive”

Default:

null

Example:

"Background"

Declared by:

This key maps to the first argument of execvp(3). If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead. This key is required in the absence of the ProgramArguments key.

Type: null or absolute path

Default:

null

Declared by:

This key maps to the second argument of execvp(3). This key is required in the absence of the Program key. Please note: many people are confused by this key. Please read execvp(3) very carefully!

Type: null or (list of string)

Default:

null

Declared by:

Much like the WatchPaths option, this key will watch the paths for modifications. The difference being that the job will only be started if the path is a directory and the directory is not empty.

Type: null or (list of string)

Default:

null

Declared by:

This optional key is used to specify a directory to chroot(2) to before running the job.

Type: null or string

Default:

null

Declared by:

This optional key is used to control whether your job is launched once at the time the job is loaded. The default is false.

Type: null or boolean

Default:

null

Declared by:

This optional key specifies whether the job participates in advanced communication with launchd. The default is false. This flag is incompatible with the inetdCompatibility key.

Type: null or boolean

Default:

null

Declared by:

This key specifies that the job should be spawned into a new security audit session rather than the default session for the context is belongs to. See auditon(2) for details.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to specify launch on demand sockets that can be used to let launchd know when to run the job. The job must check-in to get a copy of the file descriptors using APIs outlined in launch(3). The keys of the top level Sockets dictionary can be anything. They are meant for the application developer to use to differentiate which descriptors correspond to which application level protocols (e.g. http vs. ftp vs. DNS…). At check-in time, the value of each Sockets dictionary key will be an array of descriptors. Daemon/Agent writers should consider all descriptors of a given key to be to be effectively equivalent, even though each file descriptor likely represents a different networking protocol which conforms to the criteria specified in the job configuration file.

The parameters below are used as inputs to call getaddrinfo(3).

Type: null or (attribute set of (submodule))

Default:

null

Declared by:

This optional key can be used to request that the service be registered with the mDNSResponder(8). If the value is boolean, the service name is inferred from the SockServiceName.

Type: null or boolean or list of string

Default:

null

Declared by:

This optional key can be used to request that the datagram socket join a multicast group. If the value is a hostname, then getaddrinfo(3) will be used to join the correct multicast address for a given socket family. If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily family also be set, otherwise the results are undefined.

Type: null or string

Default:

null

Declared by:

This optional key is a variant of SockPathName. Instead of binding to a known path, a securely generated socket is created and the path is assigned to the environment variable that is inherited by all jobs spawned by launchd.

Type: null or string

Default:

null

Declared by:

This optional key can be used to specifically request that “IPv4” or “IPv6” socket(s) be created.

Type: null or one of “IPv4”, “IPv6”

Default:

null

Declared by:

This optional key specifies the node to connect(2) or bind(2) to.

Type: null or string

Default:

null

Declared by:

This optional key specifies whether listen(2) or connect(2) should be called on the created file descriptor. The default is true (“to listen”).

Type: null or boolean

Default:

null

Declared by:

This optional key specifies the mode of the socket. Known bug: Property lists don’t support octal, so please convert the value to decimal.

Type: null or signed integer

Default:

null

Declared by:

This optional key implies SockFamily is set to “Unix”. It specifies the path to connect(2) or bind(2) to.

Type: null or absolute path

Default:

null

Declared by:

This optional key specifies the protocol to be passed to socket(2). The only value understood by this key at the moment is “TCP”.

Type: null or value “TCP” (singular enum)

Default:

null

Declared by:

This optional key specifies the service on the node to connect(2) or bind(2) to.

Type: null or string

Default:

null

Declared by:

This optional key tells launchctl what type of socket to create. The default is “stream” and other valid values for this key are “dgram” and “seqpacket” respectively.

Type: null or one of “stream”, “dgram”, “seqpacket”

Default:

null

Declared by:

Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following keys apply:

Type: null or (submodule)

Default:

null

Declared by:

The maximum amount of cpu time (in seconds) to be used by each process.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) core file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the sbrk(2) system call.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of open files for this process. Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) to which a process’s resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the stack segment for a process; this defines how far a program’s stack segment may be extended. Stack extension is performed automatically by the system.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies what file should be used for data being sent to stderr when using stdio(3).

Type: null or absolute path

Default:

null

Declared by:

This optional key specifies what file should be used for data being supplied to stdin when using stdio(3).

Type: null or absolute path

Default:

null

Declared by:

This optional key specifies what file should be used for data being sent to stdout when using stdio(3).

Type: null or absolute path

Default:

null

Declared by:

This optional key causes the job to be started every calendar interval as specified. The semantics are much like crontab(5): Missing attributes are considered to be wildcard. Unlike cron which skips job invocations when the computer is asleep, launchd will start the job the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon waking from sleep.

Type: null or (submodule) or unique (non-empty (list of (submodule)))

Default:

null

Example:

[
  {
    Hour = 2;
    Minute = 30;
  }
]

Declared by:

This optional key causes the job to be started every N seconds. If the system is asleep, the job will be started the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon wake from sleep.

Type: null or signed integer

Default:

null

Declared by:

This optional key causes the job to be started every time a filesystem is mounted.

Type: null or boolean

Default:

null

Declared by:

This key lets one override the default throttling policy imposed on jobs by launchd. The value is in seconds, and by default, jobs will not be spawned more than once every 10 seconds. The principle behind this is that jobs should linger around just in case they are needed again in the near future. This not only reduces the latency of responses, but it encourages developers to amortize the cost of program invocation.

Type: null or signed integer

Default:

null

Declared by:

The recommended idle time out (in seconds) to pass to the job. If no value is specified, a default time out will be supplied by launchd for use by the job at check in time.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies what value should be passed to umask(2) before running the job. Known bug: Property lists don’t support octal, so please convert the value to decimal.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies the user to run the job as. This key is only applicable when launchd is running as root.

Type: null or string

Default:

null

Declared by:

This optional key specifies that launchd should instruct the kernel to have the job wait for a debugger to attach before any code in the job is executed.

Type: null or boolean

Default:

null

Declared by:

This optional key causes the job to be started if any one of the listed paths are modified.

Type: null or (list of absolute path)

Default:

null

Declared by:

This optional key is used to specify a directory to chdir(2) to before running the job.

Type: null or string

Default:

null

Declared by:

The presence of this key specifies that the daemon expects to be run as if it were launched from inetd.

Type: null or (submodule)

Default:

null

Example:

{
  Wait = true;
}

Declared by:

This flag corresponds to the “wait” or “nowait” option of inetd. If true, then the listening socket is passed via the standard in/out/error file descriptors. If false, then accept(2) is called on behalf of the job, and the result is passed via the standard in/out/error descriptors.

Type: null or boolean or string

Default:

null

Declared by:

Definition of launchd daemons.

After the system is booted and the kernel is running, launchd is run to finish the system initialization. As part of that initialization, it goes through the following steps:

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Command executed as the service’s main process.

Type: string or absolute path

Default:

""

Declared by:

Environment variables passed to the service’s processes.

Type: attribute set of (string or list of string)

Default:

{ }

Example:

{
  LANG = "nl_NL.UTF-8";
  PATH = "/foo/bar/bin";
}

Declared by:

Packages added to the service’s PATH environment variable. Only the bin and subdirectories of each package is added.

Type: list of (absolute path or string)

Default:

[ ]

Declared by:

Shell commands executed as the service’s main process.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Each attribute in this set specifies an option for a key in the plist. https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man5/launchd.plist.5.html

Type: submodule

Default:

{ }

Example:

{
  KeepAlive = true;
  Program = "/run/current-system/sw/bin/nix-daemon";
}

Declared by:

When a job dies, launchd kills any remaining processes with the same process group ID as the job. Setting this key to true disables that behavior.

Type: null or boolean

Default:

null

Declared by:

This optional key specifies that launchd should adjust its log mask temporarily to LOG_DEBUG while dealing with this job.

Type: null or boolean

Default:

null

Declared by:

This optional key is used as a hint to launchctl(1) that it should not submit this job to launchd when loading a job or jobs. The value of this key does NOT reflect the current state of the job on the running system. If you wish to know whether a job is loaded in launchd, reading this key from a configuration file yourself is not a sufficient test. You should query launchd for the presence of the job using the launchctl(1) list subcommand or use the ServiceManagement framework’s SMJobCopyDictionary() method.

Note that as of Mac OS X v10.6, this key’s value in a configuration file conveys a default value, which is changed with the [-w] option of the launchctl(1) load and unload subcommands. These subcommands no longer modify the configuration file, so the value displayed in the configuration file is not necessarily the value that launchctl(1) will apply. See launchctl(1) for more information.

Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria are insufficient to describe the conditions under which your job needs to run. The cost to have a job loaded in launchd is negligible, so there is no harm in loading a job which only runs once or very rarely.

Type: null or boolean

Default:

null

Declared by:

This flag causes launchd to use the glob(3) mechanism to update the program arguments before invocation.

Type: null or boolean

Default:

null

Declared by:

This flag instructs launchd that the job promises to use vproc_transaction_begin(3) and vproc_transaction_end(3) to track outstanding transactions that need to be reconciled before the process can safely terminate. If no outstanding transactions are in progress, then launchd is free to send the SIGKILL signal.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to specify additional environment variables to be set before running the job.

Type: null or (attribute set of string)

Default:

null

Declared by:

The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The value zero is interpreted as infinity.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies the group to run the job as. This key is only applicable when launchd is running as root. If UserName is set and GroupName is not, the the group will be set to the default group of the user.

Type: null or string

Default:

null

Declared by:

Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following keys apply:

Type: null or (submodule)

Default:

null

Example:

{
  NumberOfFiles = 4096;
}

Declared by:

The maximum amount of cpu time (in seconds) to be used by each process.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) core file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the sbrk(2) system call.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of open files for this process. Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) to which a process’s resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the stack segment for a process; this defines how far a program’s stack segment may be extended. Stack extension is performed automatically by the system.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies whether initgroups(3) should be called before running the job. The default is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to control whether your job is to be kept continuously running or to let demand and conditions control the invocation. The default is false and therefore only demand will start the job. The value may be set to true to unconditionally keep the job alive. Alternatively, a dictionary of conditions may be specified to selectively control whether launchd keeps a job alive or not. If multiple keys are provided, launchd ORs them, thus providing maximum flexibility to the job to refine the logic and stall if necessary. If launchd finds no reason to restart the job, it falls back on demand based invocation. Jobs that exit quickly and frequently when configured to be kept alive will be throttled to converve system resources.

Type: null or boolean or (submodule)

Default:

null

Declared by:

This required key uniquely identifies the job to launchd.

Type: string

Declared by:

Specifies higher-level event types to be used as launch-on-demand event sources. Each sub-dictionary defines events for a particular event subsystem, such as “com.apple.iokit.matching”, which can be used to launch jobs based on the appearance of nodes in the IORegistry. Each dictionary within the sub-dictionary specifies an event descriptor that is specified to each event subsystem. With this key, the job promises to use the xpc_set_event_stream_handler(3) API to consume events. See xpc_events(3) for more details on event sources.

Type: null or (attribute set)

Default:

null

Example:

{
  "com.apple.iokit.matching" = {
    "com.apple.usb.device" = {
      IOMatchLaunchStream = true;
      IOProviderClass = "IOUSBDevice";
      idProduct = "*";
      idVendor = "*";
    };
  };
}

Declared by:

This optional key specifies whether the job can only be run once and only once. In other words, if the job cannot be safely respawned without a full machine reboot, then set this key to be true.

Type: null or boolean

Default:

null

Declared by:

This configuration file only applies to hosts NOT listed with this key. Note: One should set kern.hostname in sysctl.conf(5) for this feature to work reliably.

Type: null or (list of string)

Default:

null

Declared by:

This configuration file only applies to the hosts listed with this key. Note: One should set kern.hostname in sysctl.conf(5) for this feature to work reliably.

Type: null or (list of string)

Default:

null

Declared by:

This configuration file only applies to sessions of the type specified. This key is used in concert with the -S flag to launchctl.

Type: null or string or list of string

Default:

null

Declared by:

This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O when the process is throttled with the Darwin-background classification.

Type: null or boolean

Default:

null

Declared by:

This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to specify Mach services to be registered with the Mach bootstrap sub-system. Each key in this dictionary should be the name of service to be advertised. The value of the key must be a boolean and set to true. Alternatively, a dictionary can be used instead of a simple true value.

Finally, for the job itself, the values will be replaced with Mach ports at the time of check-in with launchd.

Type: null or (attribute set of (boolean or (submodule)))

Default:

null

Example:

{
  "org.nixos.service" = {
    ResetAtClose = true;
  };
}

Declared by:

This optional key specifies what nice(3) value should be applied to the daemon.

Type: null or signed integer

Default:

null

Declared by:

This key was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was true. This key has been deprecated and replaced in Mac OS X 10.5 and later with the more powerful KeepAlive option.

Type: null or boolean

Default:

null

Declared by:

This optional key describes, at a high level, the intended purpose of the job. The system will apply resource limits based on what kind of job it is. If left unspecified, the system will apply light resource limits to the job, throttling its CPU usage and I/O bandwidth. The following are valid values:

Type: null or one of “Background”, “Standard”, “Adaptive”, “Interactive”

Default:

null

Example:

"Background"

Declared by:

This key maps to the first argument of execvp(3). If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead. This key is required in the absence of the ProgramArguments key.

Type: null or absolute path

Default:

null

Declared by:

This key maps to the second argument of execvp(3). This key is required in the absence of the Program key. Please note: many people are confused by this key. Please read execvp(3) very carefully!

Type: null or (list of string)

Default:

null

Declared by:

Much like the WatchPaths option, this key will watch the paths for modifications. The difference being that the job will only be started if the path is a directory and the directory is not empty.

Type: null or (list of string)

Default:

null

Declared by:

This optional key is used to specify a directory to chroot(2) to before running the job.

Type: null or string

Default:

null

Declared by:

This optional key is used to control whether your job is launched once at the time the job is loaded. The default is false.

Type: null or boolean

Default:

null

Declared by:

This optional key specifies whether the job participates in advanced communication with launchd. The default is false. This flag is incompatible with the inetdCompatibility key.

Type: null or boolean

Default:

null

Declared by:

This key specifies that the job should be spawned into a new security audit session rather than the default session for the context is belongs to. See auditon(2) for details.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to specify launch on demand sockets that can be used to let launchd know when to run the job. The job must check-in to get a copy of the file descriptors using APIs outlined in launch(3). The keys of the top level Sockets dictionary can be anything. They are meant for the application developer to use to differentiate which descriptors correspond to which application level protocols (e.g. http vs. ftp vs. DNS…). At check-in time, the value of each Sockets dictionary key will be an array of descriptors. Daemon/Agent writers should consider all descriptors of a given key to be to be effectively equivalent, even though each file descriptor likely represents a different networking protocol which conforms to the criteria specified in the job configuration file.

The parameters below are used as inputs to call getaddrinfo(3).

Type: null or (attribute set of (submodule))

Default:

null

Declared by:

This optional key can be used to request that the service be registered with the mDNSResponder(8). If the value is boolean, the service name is inferred from the SockServiceName.

Type: null or boolean or list of string

Default:

null

Declared by:

This optional key can be used to request that the datagram socket join a multicast group. If the value is a hostname, then getaddrinfo(3) will be used to join the correct multicast address for a given socket family. If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily family also be set, otherwise the results are undefined.

Type: null or string

Default:

null

Declared by:

This optional key is a variant of SockPathName. Instead of binding to a known path, a securely generated socket is created and the path is assigned to the environment variable that is inherited by all jobs spawned by launchd.

Type: null or string

Default:

null

Declared by:

This optional key can be used to specifically request that “IPv4” or “IPv6” socket(s) be created.

Type: null or one of “IPv4”, “IPv6”

Default:

null

Declared by:

This optional key specifies the node to connect(2) or bind(2) to.

Type: null or string

Default:

null

Declared by:

This optional key specifies whether listen(2) or connect(2) should be called on the created file descriptor. The default is true (“to listen”).

Type: null or boolean

Default:

null

Declared by:

This optional key specifies the mode of the socket. Known bug: Property lists don’t support octal, so please convert the value to decimal.

Type: null or signed integer

Default:

null

Declared by:

This optional key implies SockFamily is set to “Unix”. It specifies the path to connect(2) or bind(2) to.

Type: null or absolute path

Default:

null

Declared by:

This optional key specifies the protocol to be passed to socket(2). The only value understood by this key at the moment is “TCP”.

Type: null or value “TCP” (singular enum)

Default:

null

Declared by:

This optional key specifies the service on the node to connect(2) or bind(2) to.

Type: null or string

Default:

null

Declared by:

This optional key tells launchctl what type of socket to create. The default is “stream” and other valid values for this key are “dgram” and “seqpacket” respectively.

Type: null or one of “stream”, “dgram”, “seqpacket”

Default:

null

Declared by:

Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following keys apply:

Type: null or (submodule)

Default:

null

Declared by:

The maximum amount of cpu time (in seconds) to be used by each process.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) core file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the sbrk(2) system call.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of open files for this process. Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) to which a process’s resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the stack segment for a process; this defines how far a program’s stack segment may be extended. Stack extension is performed automatically by the system.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies what file should be used for data being sent to stderr when using stdio(3).

Type: null or absolute path

Default:

null

Declared by:

This optional key specifies what file should be used for data being supplied to stdin when using stdio(3).

Type: null or absolute path

Default:

null

Declared by:

This optional key specifies what file should be used for data being sent to stdout when using stdio(3).

Type: null or absolute path

Default:

null

Declared by:

This optional key causes the job to be started every calendar interval as specified. The semantics are much like crontab(5): Missing attributes are considered to be wildcard. Unlike cron which skips job invocations when the computer is asleep, launchd will start the job the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon waking from sleep.

Type: null or (submodule) or unique (non-empty (list of (submodule)))

Default:

null

Example:

[
  {
    Hour = 2;
    Minute = 30;
  }
]

Declared by:

This optional key causes the job to be started every N seconds. If the system is asleep, the job will be started the next time the computer wakes up. If multiple intervals transpire before the computer is woken, those events will be coalesced into one event upon wake from sleep.

Type: null or signed integer

Default:

null

Declared by:

This optional key causes the job to be started every time a filesystem is mounted.

Type: null or boolean

Default:

null

Declared by:

This key lets one override the default throttling policy imposed on jobs by launchd. The value is in seconds, and by default, jobs will not be spawned more than once every 10 seconds. The principle behind this is that jobs should linger around just in case they are needed again in the near future. This not only reduces the latency of responses, but it encourages developers to amortize the cost of program invocation.

Type: null or signed integer

Default:

null

Declared by:

The recommended idle time out (in seconds) to pass to the job. If no value is specified, a default time out will be supplied by launchd for use by the job at check in time.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies what value should be passed to umask(2) before running the job. Known bug: Property lists don’t support octal, so please convert the value to decimal.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies the user to run the job as. This key is only applicable when launchd is running as root.

Type: null or string

Default:

null

Declared by:

This optional key specifies that launchd should instruct the kernel to have the job wait for a debugger to attach before any code in the job is executed.

Type: null or boolean

Default:

null

Declared by:

This optional key causes the job to be started if any one of the listed paths are modified.

Type: null or (list of absolute path)

Default:

null

Declared by:

This optional key is used to specify a directory to chdir(2) to before running the job.

Type: null or string

Default:

null

Declared by:

The presence of this key specifies that the daemon expects to be run as if it were launched from inetd.

Type: null or (submodule)

Default:

null

Example:

{
  Wait = true;
}

Declared by:

This flag corresponds to the “wait” or “nowait” option of inetd. If true, then the listening socket is passed via the standard in/out/error file descriptors. If false, then accept(2) is called on behalf of the job, and the result is passed via the standard in/out/error descriptors.

Type: null or boolean or string

Default:

null

Declared by:

A set of environment variables to be set on all future processes launched by launchd in the caller’s context. The value of each variable can be either a string or a list of strings. The latter is concatenated, interspersed with colon characters.

Type: attribute set of (string or list of string)

Default:

{ }

Example:

{
  LANG = "nl_NL.UTF-8";
}

Declared by:

The default prefix of the service label. Individual services can override this by setting the Label attribute.

Type: string

Default:

"org.nixos"

Declared by:

Definition of per-user launchd agents.

When a user logs in, a per-user launchd is started. It does the following:

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Command executed as the service’s main process.

Type: string or absolute path

Default:

""

Declared by:

Environment variables passed to the service’s processes.

Type: attribute set of (string or list of string)

Default:

{ }

Example:

{
  LANG = "nl_NL.UTF-8";
  PATH = "/foo/bar/bin";
}

Declared by:

Packages added to the service’s PATH environment variable. Only the bin and subdirectories of each package is added.

Type: list of (absolute path or string)

Default:

[ ]

Declared by:

Shell commands executed as the service’s main process.

Type: strings concatenated with “\n”

Default:

""

Declared by:

Each attribute in this set specifies an option for a key in the plist. https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man5/launchd.plist.5.html

Type: submodule

Default:

{ }

Example:

{
  KeepAlive = true;
  Program = "/run/current-system/sw/bin/nix-daemon";
}

Declared by:

When a job dies, launchd kills any remaining processes with the same process group ID as the job. Setting this key to true disables that behavior.

Type: null or boolean

Default:

null

Declared by:

This optional key specifies that launchd should adjust its log mask temporarily to LOG_DEBUG while dealing with this job.

Type: null or boolean

Default:

null

Declared by:

This optional key is used as a hint to launchctl(1) that it should not submit this job to launchd when loading a job or jobs. The value of this key does NOT reflect the current state of the job on the running system. If you wish to know whether a job is loaded in launchd, reading this key from a configuration file yourself is not a sufficient test. You should query launchd for the presence of the job using the launchctl(1) list subcommand or use the ServiceManagement framework’s SMJobCopyDictionary() method.

Note that as of Mac OS X v10.6, this key’s value in a configuration file conveys a default value, which is changed with the [-w] option of the launchctl(1) load and unload subcommands. These subcommands no longer modify the configuration file, so the value displayed in the configuration file is not necessarily the value that launchctl(1) will apply. See launchctl(1) for more information.

Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria are insufficient to describe the conditions under which your job needs to run. The cost to have a job loaded in launchd is negligible, so there is no harm in loading a job which only runs once or very rarely.

Type: null or boolean

Default:

null

Declared by:

This flag causes launchd to use the glob(3) mechanism to update the program arguments before invocation.

Type: null or boolean

Default:

null

Declared by:

This flag instructs launchd that the job promises to use vproc_transaction_begin(3) and vproc_transaction_end(3) to track outstanding transactions that need to be reconciled before the process can safely terminate. If no outstanding transactions are in progress, then launchd is free to send the SIGKILL signal.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to specify additional environment variables to be set before running the job.

Type: null or (attribute set of string)

Default:

null

Declared by:

The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The value zero is interpreted as infinity.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies the group to run the job as. This key is only applicable when launchd is running as root. If UserName is set and GroupName is not, the the group will be set to the default group of the user.

Type: null or string

Default:

null

Declared by:

Resource limits to be imposed on the job. These adjust variables set with setrlimit(2). The following keys apply:

Type: null or (submodule)

Default:

null

Example:

{
  NumberOfFiles = 4096;
}

Declared by:

The maximum amount of cpu time (in seconds) to be used by each process.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) core file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the sbrk(2) system call.

Type: null or signed integer

Default:

null

Declared by:

The largest size (in bytes) file that may be created.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of open files for this process. Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum number of simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) to which a process’s resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.

Type: null or signed integer

Default:

null

Declared by:

The maximum size (in bytes) of the stack segment for a process; this defines how far a program’s stack segment may be extended. Stack extension is performed automatically by the system.

Type: null or signed integer

Default:

null

Declared by:

This optional key specifies whether initgroups(3) should be called before running the job. The default is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set.

Type: null or boolean

Default:

null

Declared by:

This optional key is used to control whether your job is to be kept continuously running or to let demand and conditions control the invocation. The default is false and therefore only demand will start the job. The value may be set to true to unconditionally keep the job alive. Alternatively, a dictionary of conditions may be specified to selectively control whether launchd keeps a job alive or not. If multiple keys are provided, launchd ORs them, thus providing maximum flexibility to the job to refine the logic and stall if necessary. If launchd finds no reason to restart the job, it falls back on demand based invocation. Jobs that exit quickly and frequently when configured to be kept alive will be throttled to converve system resources.

Type: null or boolean or (submodule)

Default:

null

Declared by:

This required key uniquely identifies the job to launchd.

Type: string

Declared by:

Specifies higher-level event types to be used as launch-on-demand event sources. Each sub-dictionary defines events for a particular event subsystem, such as “com.apple.iokit.matching”, which can be used to launch jobs based on the appearance of nodes in the IORegistry. Each dictionary within the sub-dictionary specifies an event descriptor that is specified to each event subsystem. With this key, the job promises to use the xpc_set_event_stream_handler(3) API to consume events. See xpc_events(3) for more details on event sources.

Type: null or (attribute set)

Default:

null

Example:

{
  "com.apple.iokit.matching" = {
    "com.apple.usb.device" = {
      IOMatchLaunchStream = true;
      IOProviderClass = "IOUSBDevice";
      idProduct = "*";
      idVendor = "*";
    };
  };
}

Declared by:

This optional key specifies whether the job can only be run once and only once. In other words, if the job cannot be safely respawned without a full machine reboot, then set this key to be true.

Type: null or boolean

Default:

null

Declared by:

This configuration file only applies to hosts NOT listed with this key. Note: One should set kern.hostname in sysctl.conf(5) for this feature to work reliably.

Type: null or (list of string)

Default: