AnsiblePilot — Master Ansible Automation

AnsiblePilot is the leading resource for learning Ansible automation, DevOps, and infrastructure as code. Browse over 1,400 tutorials covering Ansible modules, playbooks, roles, collections, and real-world examples. Whether you are a beginner or an experienced engineer, our step-by-step guides help you automate Linux, Windows, cloud, containers, and network infrastructure.

Popular Topics

About Luca Berton

Luca Berton is an Ansible automation expert, author of 8 Ansible books published by Apress and Leanpub including "Ansible for VMware by Examples" and "Ansible for Kubernetes by Example", and creator of the Ansible Pilot YouTube channel. He shares practical automation knowledge through tutorials, books, and video courses to help IT professionals and DevOps engineers master infrastructure automation.

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

By Luca Berton · Published 2024-01-01 · Category: troubleshooting

How to manage Linux groups with Ansible group module. Create groups, delete groups, set GIDs, manage system groups, and assign users to groups.

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

How to delete a group in Linux with Ansible?

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

ParameterDescription
nameGroup name
statepresent or absent
gidGroup ID number
systemCreate as system group
forceForce deletion (even if primary group)
localUse local commands (not LDAP/NIS)
non_uniqueAllow 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).

See also

Category: troubleshooting

Watch the video: Ansible Manage Groups: Create, Delete & Modify with group Module — Video Tutorial

Browse all Ansible tutorials · AnsiblePilot Home