A group is just a bunch of DXF entities tied together. All entities of a group has to be in the same layout (modelspace or any paperspace layout but not block). Groups can be named or unnamed, but in reality an unnamed groups has just a special name like “*Annnn”. The name of a group has to be unique in the drawing. Groups are organized in the group table, which is stored as attribute groups in the Drawing object.


Group entities have to reside in the modelspace or an paperspace layout but not in a block definition!


class ezdxf.entities.dxfgroups.DXFGroup

The group name is not stored in the GROUP entity, it is stored in the GroupCollection object.


group description (string)


1 for unnamed, 0 for named group (int)


1 for selectable, 0 for not selectable group (int)

__iter__() Iterator[DXFEntity]

Iterate over all DXF entities in DXFGroup as instances of DXFGraphic or inherited (LINE, CIRCLE, …).

__len__() int

Returns the count of DXF entities in DXFGroup.


Returns entities by standard Python indexing and slicing.

__contains__(item: str | DXFEntity) bool

Returns True if item is in DXFGroup. item has to be a handle string or an object of type DXFEntity or inherited.

handles() Iterable[str]

Iterable of handles of all DXF entities in DXFGroup.

edit_data() list[DXFEntity]

Context manager which yields all the group entities as standard Python list:

with group.edit_data() as data:
   # add new entities to a group
   data.append(modelspace.add_line((0, 0), (3, 0)))
   # remove last entity from a group
set_data(entities: Iterable[DXFEntity]) None

Set entities as new group content, entities should be an iterable of DXFGraphic (LINE, CIRCLE, …).


DXFValueError – not all entities are located on the same layout (modelspace or any paperspace layout but not block)

extend(entities: Iterable[DXFEntity]) None

Add entities to DXFGroup, entities should be an iterable of DXFGraphic (LINE, CIRCLE, …).


DXFValueError – not all entities are located on the same layout (modelspace or any paperspace layout but not block)

clear() None

Remove all entities from DXFGroup, does not delete any drawing entities referenced by this group.

audit(auditor: Auditor) None

Remove invalid entities from DXFGroup.

Invalid entities are:

  • deleted entities

  • all entities which do not reside in model- or paper space

  • all entities if they do not reside in the same layout


Each Drawing has one group table, which is accessible by the attribute groups.

class ezdxf.entities.dxfgroups.GroupCollection

Manages all DXFGroup objects of a Drawing.


Returns the count of DXF groups.


Iterate over all existing groups as (name, group) tuples. name is the name of the group as string and group is an DXFGroup object.


Returns True if a group name exist.

get(name: str) DXFGroup

Returns the group name. Raises DXFKeyError if group name does not exist.

groups() Iterator[DXFGroup]

Iterable of all existing groups.

new(name: str | None = None, description: str = '', selectable: bool = True) DXFGroup

Creates a new group. If name is None an unnamed group is created, which has an automatically generated name like “*Annnn”. Group names are case-insensitive.

  • name – group name as string

  • description – group description as string

  • selectable – group is selectable if True

delete(group: DXFGroup | str) None

Delete group, group can be an object of type DXFGroup or a group name as string.


Delete all groups.

audit(auditor: Auditor) None

Removes empty groups and invalid handles from all groups.