A group is just a bunch of DXF entities tied together. All entities of a group has to be on the same layout (modelspace or any paper 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 main group table, which is stored as attribute groups in the Drawing object.

Group entities have to be in modelspace or any 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__() → Iterable[ezdxf.entities.dxfentity.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: Union[str, ezdxf.entities.dxfentity.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[ezdxf.entities.dxfentity.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 DXFGraphic or inherited (LINE, CIRCLE, …). Raises DXFValueError if not all entities be on the same layout (modelspace or any paperspace layout but not block)

extend(entities: Iterable[DXFEntity]) → None

Add entities to DXFGroup.

clear() → None

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

audit(auditor: Auditor) → None

Remove invalid handles from DXFGroup.

Invalid handles are: deleted entities, not all entities in the same layout or entities in a block 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.

__len__() → int

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.

__contains__(name: str) → bool

Returns True if a group name exist.

get(name: str)DXFGroup

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


Iterable of all existing groups.

new(name: str = 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”.

  • name – group name as string

  • description – group description as string

  • selectable – group is selectable if True

delete(group: Union[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.