`grp`

The Python grp module provides an interface to the Unix group database, letting you look up group entries by name or numeric ID. It’s available on Unix systems and is not provided on Windows, WASI, Android, or iOS.

Here’s a quick example:

>>> import grp

>>> grp.getgrnam("root")
grp.struct_group(gr_name='root', gr_passwd='x', gr_gid=0, gr_mem=[])

Key Features

Looks up group entries by group name using getgrnam()
Looks up group entries by numeric group ID using getgrgid()
Iterates over every available group entry using getgrall()
Returns tuple-like struct_group objects with named attributes for the group name, password, GID, and members
Complements the pwd module, which exposes the user database

Frequently Used Classes and Functions

Object	Type	Description
`grp.getgrnam()`	Function	Returns the group entry matching a given group name
`grp.getgrgid()`	Function	Returns the group entry matching a given numeric group ID
`grp.getgrall()`	Function	Returns a list of all available group entries in arbitrary order
`grp.struct_group`	Class	Represents a single group entry with `gr_name`, `gr_passwd`, `gr_gid`, and `gr_mem` attributes

Each struct_group object behaves like a tuple and exposes four fields:

gr_name: The name of the group
gr_passwd: The encrypted group password, often empty on modern systems
gr_gid: The numerical group ID
gr_mem: A list of user names that belong to the group

Examples

Looking up a group by name:

>>> import grp

>>> entry = grp.getgrnam("root")
>>> entry.gr_name
'root'
>>> entry.gr_gid
0
>>> entry.gr_mem
[]

Looking up a group by its numeric GID:

>>> import grp

>>> grp.getgrgid(0)
grp.struct_group(gr_name='root', gr_passwd='x', gr_gid=0, gr_mem=[])

Iterating over every group on the system:

>>> import grp

>>> for entry in grp.getgrall()[:3]:
...     print(entry.gr_gid, entry.gr_name)
...
0 root
1 daemon
2 bin

Handling a missing group entry:

>>> import grp

>>> grp.getgrnam("no-such-group")
Traceback (most recent call last):
  ...
KeyError: "getgrnam(): name not found: 'no-such-group'"

Common Use Cases

The most common tasks for grp include:

Resolving a numeric GID returned by os.stat() into a human-readable group name
Validating that a configured group exists before launching a service or dropping privileges
Listing every group a script or daemon can interact with on the host
Checking which users belong to an administrative group, such as wheel or sudo
Pairing group lookups with the pwd module to resolve file ownership end to end

Real-World Example

Consider a script that reports the owning group of a file in plain English instead of just printing a numeric GID:

import grp
import os
import sys

def describe_group(path):
    stat_result = os.stat(path)
    group = grp.getgrgid(stat_result.st_gid)
    members = ", ".join(group.gr_mem) or "no explicit members"
    return (
        f"{path} is owned by group {group.gr_name!r} "
        f"(GID {group.gr_gid}) with {members}"
    )

if __name__ == "__main__":
    print(describe_group(sys.argv[1]))

Run it on the command line:

$ python file_group.py /etc/passwd
/etc/passwd is owned by group 'root' (GID 0) with no explicit members

The grp.getgrgid() call turns the raw GID from os.stat() into a descriptive struct_group object, so the script can show the group name and members without having to parse /etc/group by hand.

The subprocess Module: Wrapping Program With Python

Tutorial

The subprocess Module: Wrapping Programs With Python

In this tutorial, you'll learn how to leverage other apps and programs that aren't Python, wrapping them or launching them from your Python scripts using the subprocess module. You'll learn about processes all the way up to interacting with a process as it executes.

intermediate devops stdlib

For additional information on related topics, take a look at the following resources: