# osx_defaults – Manage macOS user defaults

- Synopsis

- Parameters

- Notes

- Examples

- Status

## Synopsis

- osx_defaults allows users to read, write, and delete macOS user defaults from Ansible scripts.

- macOS applications and other programs use the defaults system to record user preferences and other information that must be maintained when the applications are not running (such as default font for new documents, or the position of an Info panel).

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---

array_add
boolean

Choices:
- no ←
- yes

Add new elements to the array for a key which has an array as its value.

domain string | Default: "NSGlobalDomain" | The domain is a domain name of the form `com.companyname.appname`.
host string |  | The host on which the preference should apply. The special value `currentHost` corresponds to the `-currentHost` switch of the defaults commandline tool.
key string / required |  | The key of the user preference.
path string | Default: "/usr/bin:/usr/local/bin" | The path in which to search for `defaults`.

state
string

Choices:
- absent
- list
- present ←

The state of the user defaults.
If set to `list` will query the given parameter specified by `key`. Returns 'null' is nothing found or mis-spelled.
`list` added in version 2.8.

type
string

Choices:
- array
- bool
- boolean
- date
- float
- int
- integer
- string ←

The type of value to write.

value raw |  | The value to write. Only required when `state=present`.

## Notes

Note

- Apple Mac caches defaults. You may need to logout and login to apply the changes.

## Examples

    - osx_defaults:
        domain: com.apple.Safari
        key: IncludeInternalDebugMenu
        type: bool
        value: true
        state: present

    - osx_defaults:
        domain: NSGlobalDomain
        key: AppleMeasurementUnits
        type: string
        value: Centimeters
        state: present

    - osx_defaults:
        domain: /Library/Preferences/com.apple.SoftwareUpdate
        key: AutomaticCheckEnabled
        type: int
        value: 1
      become: yes

    - osx_defaults:
        domain: com.apple.screensaver
        host: currentHost
        key: showClock
        type: int
        value: 1

    - osx_defaults:
        key: AppleMeasurementUnits
        type: string
        value: Centimeters

    - osx_defaults:
        key: AppleLanguages
        type: array
        value:
          - en
          - nl

    - osx_defaults:
        domain: com.geekchimp.macable
        key: ExampleKeyToRemove
        state: absent

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]

- This module is maintained by the Ansible Community. [community]

### Authors

- Franck Nijhof (@frenck)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.