# group – Add or remove groups

- Synopsis
- Requirements
- Parameters
- See Also
- Examples
- Status

## Synopsis

- Manage presence of groups on a host.
- For Windows targets, use the win_group module instead.

## Requirements

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

- groupadd
- groupdel
- groupmod

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
gid integer |  | Optional GID to set for the group.

local
boolean
added in 2.6

Choices:
- no ←
- yes

Forces the use of "local" command alternatives on platforms that implement it.
This is useful in environments that use centralized authentication when you want to manipulate the local groups. (e.g. it uses `lgroupadd` instead of `groupadd`).
This requires that these commands exist on the targeted host, otherwise it will be a fatal error.

name string / required |  | Name of the group to manage.

non_unique
boolean
added in 2.8

Choices:
- no ←
- yes

This option allows to change the group ID to a non-unique value. Requires `gid`.
Not supported on macOS or BusyBox distributions.

state
string

Choices:
- absent
- present ←

Whether the group should be present or not on the remote host.

system
boolean

Choices:
- no ←
- yes

If yes, indicates that the group created is a system group.

## See Also

See also

user – Manage user accounts
  The official documentation on the user module.
win_group – Add and remove local groups
  The official documentation on the win_group module.

## Examples

    - name: Ensure group "somegroup" exists
      group:
        name: somegroup
        state: present

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Stephen Fromm (@sfromm)

Hint

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