I have a group of objects named MyGroup. I can add a group instance with Shift+A -> Group Instance -> MyGroup, but I can't figure out how to do it from python scripting.

I'd like to add an instance of MyGroup, calling it by it's name from a script on python.

Something like the bpy.ops.mesh.primitive_plane_add() operation, but instead of adding a plane, i want to add a group instance.

Is there any way I can do this? all I could find about groups was this http://www.blender.org/api/blender_python_api_2_74_release/bpy.ops.group.html but it does not speak about adding group instances.

  • $\begingroup$ I had the exact same question yesterday ! It is indeed hard to find examples. $\endgroup$
    – nantille
    Commented May 12, 2015 at 7:33
  • $\begingroup$ I know it sounds illogical but if you were looking for adding a group instance, you'd have found it under bpy.ops.object: blender.org/api/blender_python_api_2_74_release/… $\endgroup$
    – nantille
    Commented May 12, 2015 at 7:58

2 Answers 2


This creates instances of the group, it works by first adding an Empty, and setting its .dupli_type and .dupli_group attributes. I believe for all intents this is functionally equivalent to a group instance.

import bpy

scene = bpy.context.scene

group = bpy.data.groups['CubeGroup']    
instance = bpy.data.objects.new('dupli_group', None)
instance.dupli_type = 'GROUP'
instance.dupli_group = group

(credit to: blenderartists.org user Atom)

For completeness, this is how to create groups via the API. This expects the name (string) of a group, and will add any objects in the objs collection to this group.

def to_group(named, objs):
    named:   (string) name of group to use, or to create if not present 
    objs:    a collection of object references
    groups = bpy.data.groups

    # alias existing group, or generate new group and alias that
    group = groups.get(named, groups.new(named))

    for obj in objs:
        if obj.name not in group.objects:
  • 1
    $\begingroup$ How counter intuitive !! I would never have found these dupli_ attributes. At least that works perfectly. Thanks ! $\endgroup$
    – nantille
    Commented May 12, 2015 at 8:53
  • $\begingroup$ yeah, me either. it's a maze sometimes. $\endgroup$
    – zeffii
    Commented May 12, 2015 at 8:54

I think zeffii is close to the right answer but I can't get it to work. Meanwhile I found on the Blender documentation page an operator that works if invoked properly. I wish to avoid using operators but here you go. Let's say you have a group called my_group, adding an instance to the scene works with this:

    name='my_group', group='my_group', view_align=False,
    location=(0.0, 0.0, 0.0),
    rotation=(0.0, 0.0, 0.0),
    layers=(True, False, False, False, False,
            False, False, False, False, False,
            False, False, False, False, False,
            False, False, False, False, False)

Please note that name and group parameters require the same value (here 'my_group') so that this works.

  • $\begingroup$ it didn't work for me, it says that can't find the keyword name... maybe we are using different versions of blender? (sorry! my bad! forgot to say that I'm using v2.63), maybe you should put your version of blender in your answer, just for completeness ;). Btw, why did you add so many Falses at the end? $\endgroup$
    – Bengalaa
    Commented May 12, 2015 at 13:27
  • $\begingroup$ This worked on Blender 2.74. I think I have version 2.64 somewhere so I'll give it a try. $\endgroup$
    – nantille
    Commented May 12, 2015 at 13:31

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .