community.general.homebrew module – Package manager for Homebrew

Note

This module is part of the community.general collection (version 10.0.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.homebrew.

Synopsis

  • Manages Homebrew packages

Requirements

The below requirements are needed on the host that executes this module.

  • homebrew must already be installed on the target system

Parameters

Parameter

Comments

force_formula

boolean

added in community.general 9.0.0

Force the package(s) to be treated as a formula (equivalent to brew --formula).

To install a cask, use the community.general.homebrew_cask module.

Choices:

  • false ← (default)

  • true

install_options

aliases: options

list / elements=string

options flags to install a package.

name

aliases: formula, package, pkg

list / elements=string

A list of names of packages to install/remove.

path

path

A : separated list of paths to search for brew executable. Since a package (formula in homebrew parlance) location is prefixed relative to the actual path of brew command, providing an alternative brew path enables managing different set of packages in an alternative location in the system.

Default: "/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin"

state

string

state of the package.

Choices:

  • "absent"

  • "head"

  • "installed"

  • "latest"

  • "linked"

  • "present" ← (default)

  • "removed"

  • "uninstalled"

  • "unlinked"

  • "upgraded"

update_homebrew

boolean

update homebrew itself first.

Choices:

  • false ← (default)

  • true

upgrade_all

aliases: upgrade

boolean

upgrade all homebrew packages.

Choices:

  • false ← (default)

  • true

upgrade_options

list / elements=string

added in community.general 0.2.0

Option flags to upgrade.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • When used with a loop: each package will be processed individually, it is much more efficient to pass the list directly to the name option.

Examples

# Install formula foo with 'brew' in default path
- community.general.homebrew:
    name: foo
    state: present

# Install formula foo with 'brew' in alternate path (/my/other/location/bin)
- community.general.homebrew:
    name: foo
    path: /my/other/location/bin
    state: present

# Update homebrew first and install formula foo with 'brew' in default path
- community.general.homebrew:
    name: foo
    state: present
    update_homebrew: true

# Update homebrew first and upgrade formula foo to latest available with 'brew' in default path
- community.general.homebrew:
    name: foo
    state: latest
    update_homebrew: true

# Update homebrew and upgrade all packages
- community.general.homebrew:
    update_homebrew: true
    upgrade_all: true

# Miscellaneous other examples
- community.general.homebrew:
    name: foo
    state: head

- community.general.homebrew:
    name: foo
    state: linked

- community.general.homebrew:
    name: foo
    state: absent

- community.general.homebrew:
    name: foo,bar
    state: absent

- community.general.homebrew:
    name: foo
    state: present
    install_options: with-baz,enable-debug

- name: Install formula foo with 'brew' from cask
  community.general.homebrew:
    name: homebrew/cask/foo
    state: present

- name: Use ignore-pinned option while upgrading all
  community.general.homebrew:
    upgrade_all: true
    upgrade_options: ignore-pinned

- name: Force installing a formula whose name is also a cask name
  community.general.homebrew:
    name: ambiguous_formula
    state: present
    force_formula: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed_pkgs

list / elements=string

added in community.general 0.2.0

List of package names which are changed after module run

Returned: success

Sample: ["git", "git-cola"]

msg

string

if the cache was updated or not

Returned: always

Sample: "Changed: 0, Unchanged: 2"

unchanged_pkgs

list / elements=string

added in community.general 0.2.0

List of package names which are unchanged after module run

Returned: success

Sample: ["awscli", "ag"]

Authors

  • Indrajit Raychaudhuri (@indrajitr)

  • Daniel Jaouen (@danieljaouen)

  • Andrew Dunham (@andrew-d)