Ansible Manage Groups: Create, Delete & Modify with group Module

How to delete a group in Linux with Ansible?

I'm going to show you a live Playbook with some simple Ansible code. I'm Luca Berton and welcome to today's episode of Ansible Pilot

See also: Ansible group Module: Create & Manage Linux Groups (ansible.builtin.group)

Ansible deletes a group account

• ansible.builtin.group • Add or remove groups

Today we're talking about the Ansible module group. The full name is ansible.builtin.group, which means that is part of the collection of modules "builtin" with ansible and shipped with it. It's a module pretty stable and out for years. It adds or removes groups. It supports a huge variety of Linux distributions and macOS. It relies on three Linux commands: groupadd, groupdel and groupmod. For Windows, use the ansible.windows.win_group module instead.

Parameters

• name string - group name • state string - present/absent • local string - "local" command alternatives

This module has some parameters to perform some tasks. The only required is "name", which is the group name. The "state" parameter allows us to create or delete a group, in our use case set to "absent" to delete a group. The "local" parameter allows using the "local" command alternatives on platforms that implement it if you have a central authentication system.

## Playbook

Let's jump in a real-life Ansible Playbook to delete a group.

code

• group_delete.yml

---
- name: group module Playbook
  hosts: all
  become: true
  vars:
    mygroup: "example"
  tasks:
    - name: delete group
      ansible.builtin.group:
        name: "{{ mygroup }}"
        state: absent

execution

output

$ ansible-playbook -i Playbook/inventory group/delete.yml
PLAY [group module Playbook] **************************************************************************
TASK [Gathering Facts] ****************************************************************************
ok: [demo.example.com]
TASK [delete group] *******************************************************************************
changed: [demo.example.com]
PLAY RECAP ****************************************************************************************
demo.example.com           : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

verification

$ ssh devops@demo.example.com
[devops@demo ~]$ sudo su
[root@demo devops]# getent group | grep example
[root@demo devops]# getent group
root:x:0:
bin:x:1:
daemon:x:2:
sys:x:3:
adm:x:4:
tty:x:5:
disk:x:6:
lp:x:7:
mem:x:8:
kmem:x:9:
wheel:x:10:
cdrom:x:11:
mail:x:12:
man:x:15:
dialout:x:18:
floppy:x:19:
games:x:20:
tape:x:33:
video:x:39:
ftp:x:50:
lock:x:54:
audio:x:63:
users:x:100:devops
nobody:x:65534:
dbus:x:81:
utmp:x:22:
utempter:x:35:
input:x:999:
kvm:x:36:
render:x:998:
systemd-journal:x:190:
systemd-coredump:x:997:
systemd-resolve:x:193:
tss:x:59:
polkitd:x:996:
ssh_keys:x:995:
unbound:x:994:
sssd:x:993:
chrony:x:992:
sshd:x:74:
vagrant:x:1000:
vboxsf:x:991:
slocate:x:21:

code with ❤️ in GitHub

See also: Ansible Create User Account: user Module Complete Guide

Conclusion

Now you know how to delete a group in Linux with Ansible.

Remove a Group

- name: Remove the old-project group
  ansible.builtin.group:
    name: old-project
    state: absent
  become: true

See also: Ansible Password Expiration: Manage User Account Aging & Policies

Remove Multiple Groups

- name: Remove decommissioned groups
  ansible.builtin.group:
    name: "{{ item }}"
    state: absent
  loop:
    - contractors
    - temp-access
    - old-project
  become: true

Safe Removal (Check Members First)

- name: Check group members
  ansible.builtin.command: "getent group {{ target_group }}"
  register: group_info
  changed_when: false
  failed_when: false
- name: Show group members
  ansible.builtin.debug:
    msg: "Members: {{ group_info.stdout.split(':')[3] | default('none') }}"
  when: group_info.rc == 0
- name: Remove group if empty
  ansible.builtin.group:
    name: "{{ target_group }}"
    state: absent
  when:
    - group_info.rc == 0
    - group_info.stdout.split(':')[3] | default('') | length == 0
  become: true

Remove Users from Group First

- name: Remove all users from group
  ansible.builtin.command: "gpasswd -d {{ item }} old-project"
  loop: "{{ group_members }}"
  ignore_errors: true
  become: true
- name: Remove the group
  ansible.builtin.group:
    name: old-project
    state: absent
  become: true

Create vs Delete Comparison

# Create a group
- ansible.builtin.group:
    name: developers
    gid: 1500
    state: present
# Delete a group
- ansible.builtin.group:
    name: developers
    state: absent

Windows Group Removal

- name: Remove Windows local group
  ansible.windows.win_group:
    name: OldTeam
    state: absent

FAQ

What happens to files owned by a deleted group?

Files keep their GID but show a numeric ID instead of a name. Find them with:

- name: Find orphaned files
  ansible.builtin.command: "find / -nogroup -ls"
  register: orphans
  changed_when: false
  become: true

Can I delete a group that is a user's primary group?

No - you'll get an error. Remove or reassign the user first.

Is group removal idempotent?

Yes - running state: absent on a non-existent group succeeds without error.

Delete a Group

- name: Remove old application group
  ansible.builtin.group:
    name: oldapp
    state: absent
  become: true

Create a Group

- ansible.builtin.group:
    name: appgroup
    state: present
  become: true
# With specific GID
- ansible.builtin.group:
    name: myapp
    gid: 1500
    state: present
  become: true
# System group
- ansible.builtin.group:
    name: myservice
    system: true
    state: present
  become: true

Manage Multiple Groups

- name: Create application groups
  ansible.builtin.group:
    name: "{{ item.name }}"
    gid: "{{ item.gid | default(omit) }}"
    state: present
  loop:
    - { name: webteam, gid: 2001 }
    - { name: dbteam, gid: 2002 }
    - { name: devops, gid: 2003 }
  become: true

User + Group Management

- name: Create group
  ansible.builtin.group:
    name: deploy
    state: present
  become: true
- name: Create user in group
  ansible.builtin.user:
    name: deployer
    group: deploy
    groups: [docker, sudo]
    append: true
  become: true

Remove Users Before Group

# Must remove users from group before deleting
- name: Remove users from group
  ansible.builtin.user:
    name: "{{ item }}"
    groups: ""
    append: false
  loop: [alice, bob]
  become: true
  ignore_errors: true
- name: Delete group
  ansible.builtin.group:
    name: oldteam
    state: absent
  become: true

Check Group Exists

- command: getent group myapp
  register: group_check
  changed_when: false
  failed_when: false
- ansible.builtin.group:
    name: myapp
    state: present
  when: group_check.rc != 0
  become: true

group Module Parameters

| Parameter | Description | |-----------|-------------| | name | Group name | | state | present or absent | | gid | Group ID number | | system | Create as system group | | force | Force deletion (even if primary group) | | local | Use local commands (not LDAP/NIS) | | non_unique | Allow duplicate GIDs |

FAQ

"group is primary group" error when deleting?

The group is a user's primary group. Remove or reassign users first:

- user: { name: olduser, state: absent, remove: true }
  become: true
- group: { name: oldgroup, state: absent }
  become: true

How do I change a group's GID?

- group: { name: myapp, gid: 2000 }
  become: true
# Warning: existing files won't update to new GID automatically

Can I manage Windows groups?

Use ansible.windows.win_group:

- win_group:
    name: MyAppUsers
    state: present

Create a Group

- ansible.builtin.group:
    name: developers
    state: present
  become: true

Delete a Group

- group:
    name: old-team
    state: absent
  become: true

Create with Specific GID

- group:
    name: myapp
    gid: 1500
    state: present
  become: true

System Group

- group:
    name: myservice
    system: true
    state: present
  become: true
# System groups typically get GIDs below 1000

Multiple Groups

- group:
    name: "{{ item }}"
    state: present
  loop:
    - developers
    - operations
    - security
    - qa
  become: true

Create Group Then Add Users

- group:
    name: developers
    state: present
  become: true
- user:
    name: "{{ item }}"
    groups: [developers]
    append: true  # Don't remove from other groups
  loop: [alice, bob, charlie]
  become: true

Non-Unique GID

# Allow multiple groups to share a GID
- group:
    name: alias-group
    gid: 1500
    non_unique: true
    state: present
  become: true

Full User + Group Setup

- name: Create all groups
  group:
    name: "{{ item.name }}"
    gid: "{{ item.gid | default(omit) }}"
  loop:
    - { name: developers, gid: 2000 }
    - { name: operations, gid: 2001 }
    - { name: docker }
  become: true
- name: Create users with groups
  user:
    name: "{{ item.name }}"
    group: "{{ item.primary }}"
    groups: "{{ item.secondary }}"
    append: true
  loop:
    - { name: alice, primary: developers, secondary: [docker, sudo] }
    - { name: bob, primary: operations, secondary: [docker] }
  become: true

Verify Group Exists

- getent:
    database: group
    key: developers
  register: group_info
  ignore_errors: true
- debug:
    msg: "Group exists with GID {{ ansible_facts.getent_group.developers[1] }}"
  when: group_info is success

FAQ

Can I rename a group?

No — the group module doesn't support renaming. Create the new group, move users, delete the old one.

What happens if I delete a group with members?

The group is removed but users keep their other group memberships. Their files retain the old GID numerically.

group vs user module for group membership?

group manages group existence (create/delete). user manages group membership (which users belong to which groups).

Related Articles

• become directives in Ansible • organizing hosts with Ansible inventory • role dependencies in Ansible • Windows fleet automation with Ansible

See also

• Ansible subscription-manager: Register RHEL with redhat_subscription Module