dcgmi group#

NAME#

dcgmi-group - create and manage groups of DCGM entities

SYNOPSIS#

dcgmi group (--list | -l) [--json] [--host <address>]
dcgmi group (--create | -c) <name>
            [--default | --defaultnvswitches | --add <entities>]
            [--host <address>]
dcgmi group (--delete | -d) <group-id> [--host <address>]
dcgmi group --group <group-id> --info [--json] [--host <address>]
dcgmi group --group <group-id> --add <entities> [--host <address>]
dcgmi group --group <group-id> --remove <entities> [--host <address>]

DESCRIPTION#

dcgmi group manages persistent host-engine groups. A group gives other dcgmi commands and the DCGM APIs a stable target for operations that should apply to several entities together.

Despite the historical option descriptions, a group is not limited to GPUs. It can contain any entity type accepted by the entity-list parser, including MIG instances, CPUs, NVSwitches, ConnectX devices, and link entities.

OPTIONS#

-l, --list: List persistent groups on the host engine.
-c <name>, --create <name>: Create an empty group with the specified name. Combine this option with one of the population options to add initial members.
--default: Initially populate a new group with all available GPUs. Do not combine with --defaultnvswitches.
--defaultnvswitches: Initially populate a new group with all available NVSwitches. Do not combine with --default.
-d <group-id>, --delete <group-id>: Delete a persistent group.
-g <group-id>, --group <group-id>: Select the persistent group used by --info, --add, or --remove.
-i, --info: Display the name and members of the selected group.
-a <entities>, --add <entities>: Add a comma-separated entity list to a new or existing group. See dcgmi for selector names, ranges, links, and MIG wildcard forms. When creating a group, do not combine this option with --default or --defaultnvswitches; DCGM 4.6 ignores the explicit list for those two built-in population modes.
-r <entities>, --remove <entities>: Remove a comma-separated entity list from an existing group.
-j, --json: Use JSON for --list or --info output. See JSON output.
--host <address>: Connect to the specified host engine.
-h, --help: Print generated usage information and exit.

GROUP IDS AND LIFETIME#

The host engine assigns a numeric ID when a group is created. Use dcgmi group --list rather than hard-coding an ID; the listing also shows the host engine’s built-in system groups. A user-created group may be empty.

Here, persistent means that the group remains after the creating dcgmi client disconnects. Groups are objects in the running host engine, not durable configuration files, and are lost when that host-engine process exits.

Group membership is only a reusable selector. A consuming command still determines which entity types and combinations it supports. Deleting a group does not necessarily undo operations previously applied through it. In particular, GPU configuration is stored on the individual GPUs and remains after its group is deleted; see dcgmi config.

CAPACITY LIMITS#

A host engine supports at most 64 entity groups across all connected clients. The built-in all-GPUs and all-NVSwitches groups count toward this total, so a normally initialized host engine has capacity for up to 62 additional groups. Deleting a user-created group frees one of those slots.

Each group can contain at most 1,024 entities. Creating a group after the host-engine limit is reached or adding an entity to a full group fails with DCGM_ST_MAX_LIMIT.

EXAMPLES#

Create a group containing GPUs 0 and 1:

$ dcgmi group --create training-gpus --add gpu:0,gpu:1

Create a group containing every available GPU:

$ dcgmi group --create all-available --default

List groups and inspect group 3:

$ dcgmi group --list

$ dcgmi group --group 3 --info

Add CPUs 0 through 3 and remove GPU 1:

$ dcgmi group --group 3 --add 'cpu:{0-3}'

$ dcgmi group --group 3 --remove gpu:1