# Add a group instance with python

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.

• I had the exact same question yesterday ! It is indeed hard to find examples. – nantille May 12 '15 at 7:33
• 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/… – nantille May 12 '15 at 7:58

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:

• How counter intuitive !! I would never have found these dupli_ attributes. At least that works perfectly. Thanks ! – nantille May 12 '15 at 8:53
• yeah, me either. it's a maze sometimes. – zeffii May 12 '15 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:

bpy.ops.object.group_instance_add(
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.

• 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? – Bengalaa May 12 '15 at 13:27
• This worked on Blender 2.74. I think I have version 2.64 somewhere so I'll give it a try. – nantille May 12 '15 at 13:31