Update Addons with both Blender 2.8 and 2.7 Support

The easiest and first update you should make to support your addon in Blender 2.8: update the `bl_info: blender` field to say (2,80,0) or higher. Blender will show this warning if a lower version is displayed (such as this wrong notation of (2,8,0)):

Even if the rest of your code is working for 2.8, Blender still won’t let you enable or use the addon without this change.

This is a little bit of an unfortunate however. To use the same python/zip file for 2.8 and 2.7 installs, you force 2.7 users to see a “may not work” warning. My personal take is – yes, you should plan to distribute two versions of any addon; One with bl_info set for 2.8, and the other for 2.7. Beyond this, do your best to ensure this is the only difference between your 2.7 and 2.8 code! Keep reading on how to make this possible.

In the past, you could be somewhat lazy and put this line in your register function to auto register all classes in the entire addon, even across files bpy.utils.register_module(__name__).

Now, those days are gone. You have to register classes explicitly and one-by-one. This is definitely a move for the better – I have seen many addons that have had weird behaviors or even fail on enable due to issues of using this shortcut and classes registering in a random order.

See this recommended pattern, limiting code duplication:

# List of the name of the classes inherited from Blender types like AddonPreferences, Operator, Panel etc
# order matters, e.g. if those operators depend on MyPropertyGroup
classes = (
    MyAddonPreferences,
    MyPropertyGroup,
    ADDON_OT_some_operator,
    ADDON_OT_some_other_operator,
    ADDON_PT_some_panel
)

def register():
    for cls in classes:
        make_annotations(cls) # what is this? Read the section on annotations above!
        bpy.utils.register_class(cls)

def unregister():  # note how unregistering is done in reverse
    for cls in reversed(classes):
        bpy.utils.unregister_class(cls)

Furthermore, if you are doing no other property registration or funny things like the make_annotations above, you can even use this builtin shortcut instead of manually defining register and unregister functions.

classes = (
    MyAddonPreferences,
    MyPropertyGroup,
    ADDON_OT_some_operator,
    ADDON_OT_some_other_operator,
    ADDON_PT_some_panel
)
register, unregister = bpy.utils.register_classes_factory(classes)

One of the major workflow shifts of Blender 2.8 is the movement from the previous visual layers and groups into the world of collections. At a first glance, most code can very simply be updated from bpy.data.groups to bpy.data.collections, but there are a few more nuances to understand:

• All blender scenes by default will start with a collection bpy.data.collections['Collections']
• Instead of the original 20 layers in 2.7, users will toggle visibility of collections or “View Layers”, which can be even nested sets of collections. Check out this page for more details, noting also the 2.8 concept of View Layers.
• As you add new objects to a scene, you are simultaneously adding them to the scene’s default collection if it has one, or the scene’s master collection. Removing an object from all collections is the equivalent to removing it from the scene itself, much like in blender 2.7x we have context.scene.objects.unlink()
• Thus, beware of code that makes assumptions of object visibility not being tied to group/collection membership!
• Be also mindful of the concept of a scene’s “master collection” which is accessed via bpy.data.scene["Scene"].collection, which is not available through bpy.data.collections.

Getting a groups vs collections

Want to update your code to work with groups in 2.8? Try this snippet out, so it can keep working on blender 2.7 as well.

...
if hasattr(bpy.data, "collections"):
    mygroup = bpy.data.collections.get("MyGroup")
else:
    mygroup = bpy.data.groups.get("MyGroup")
...

It is a bit funny to be grabbing a collection and naming it as though it were a group, so as you make your updates consider also generalizing the terminology away from “groups” and “collections” where it makes sense.

Taking a look at layers

If you have 2.7 code dealing with changing viewport layers, you will have to make some adjustments to fit Blender 2.8. This page here has good 2.7 vs 2.8 example code, but how would you approach this in a cross-compatibility way? Here is one complete example that force uses collections in 2.8 to behave in a similar way as layers in 2.7:

def layers_get(object):
    """Gets membership of object in 0-19 numbered layers/collections

    returns: list of booleans with length of 20
    """
    if hasattr(object, "layers"):
        return object.layers
    else:
        obj_colls = object.users_collection # get all collections object is in
        collection_names = [coll.name for coll in obj_colls]
        return [str(i) in collection_names for i in range(20)] # ordered bool list


def layers_set(object, layers=[], context=None):
    """Assign layers or assign/crate collections with 2.7/2.8 support

    Arguments:
        object: valid object from bpy.data.objects
        layers: list of bools with a length of 20
    """
    if hasattr(object, "layers"):
        # Blender 2.7x branch
        object.layers = layers  # raises exception if not a bool list of len 20
        return
    
    # Blender 2.8x branch, apply layers checks to force consistency with 2.7
    if not context:
        context = bpy.context
    if len(layers) != 20:
        # artificially force consistency with 2.8 layer counts
        raise Exception("Length of layers should be 20")
    elif sum([not isinstance(n, bool) for n in layers])>0:
        # force that the list of layers is bools only
        raise Exception("All layers elements must be booleans")
    
    # Create collection and assign object
    for i, layer in enumerate(layers):
        if str(i) not in bpy.data.collections and layer is False:
            continue # collection doesn't exist, but not 'enabling layer' anyways
        elif str(i) not in bpy.data.collections and layer is True:
            collection = bpy.data.collections.new(name=str(i)) # create new one
            context.scene.collection.children.link(collection) # add to scene
        else:
            collection = bpy.data.collections[str(i)] # careful of linked libraries!
        
        # now assign "layer visibility" by adding or removing to named collection
        if layer is True:
            # add object to layer if not already present
            if object in collection.objects[:]:
                continue
            else:
                collection.objects.link(object)
        else:
            # remove object from layer if present
            if object not in collection.objects[:]:
                continue
            else:
                collection.objects.unlink(object)

This code block implements layers_get and layers_set methods. In 2.7, it simply toggles the visibility of each  viewport layer, which are unnamed. In Blender 2.8, these functions translate this list of booleans into dynamically generated collections with names like ‘0’, ‘1’, ‘2’ etc. It will then check inclusion in, add to, or remove objects from these collections. Below is an example using these two functions in both Blender 2.7 and 2.8:

object = bpy.data.objects['Cube']
layers = [True]*2 + [False]*18 # enables first two "layers"
layers_set(object, layers, bpy.context)
print(layers_get(object))

This approach is really force-feeding 2.7 style of layer management into 2.8, so I wouldn’t recommend using it directly as-is. Rather, aim to explicitly manage the collections/layers your addon cares about through functional collection names, and avoid generating unnecessary or unused collections.

Something to be aware of, instead of getting all light type objects via bpy.data.lights you now have you use bpy.data.lights. How about the cross compatible way of of, say, creating a new light source?

def new_light(name, lamp_type):
    """Create a lamp in a cross compatible way, and add to scene"""
    if hasattr(bpy.data, "lights"): # the 2.8 way
        if lamp_type not in ("POINT", "SUN", "AREA", "SPOT"):
            raise Exception("Invalid type of light for blender 2.8")
        return bpy.data.lights.new(name, lamp_type)
    else:
        if lamp_type not in ("POINT", "SUN", "AREA", "SPOT", "HEMI"):
            raise Exception("Invalid type of light for blender 2.7")
        return bpy.data.lamps.new(name, lamp_type)

Update checks for lamp types

Personally, I got tripped up in updating some code because I had type checks like if object.type == "LAMP":... because this wasn’t creating outright errors – but it of course wasn’t doing anything for my lights as their type name has changed. This snippet would be the best way to detect light/lamp-type objects in both 2.7 and 2.8:

if object.type in ("LIGHT", "LAMP"):
    ...

Additionally, as the section title indicates, there is no longer the type of light called “Hemi”. If you had a scene created in blender 2.7 with any Hemi lamps, they are converted to Sun lamps in blender 2.8. Take that into consideration if you have any code which deals with hemis, and certainly don’t go trying to create hemi-type lamps in blender 2.8!

When I say UI location, what I really mean is for example the tabs of the 3D toolshelf you find in 2.79 is now on the right side of the 3D viewport. But not only that, sometimes the indicator names for these locations have also changed. For instance, to make a custom panel show up on the right-hand side toolshelf, you could write:

class ADDON_PT_my_toolshelf_panel(bpy.types.Panel):
    ...     
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'TOOLS' if bpy.app.version < (2, 80) else 'UI'
    bl_category = "Tools"
    ...

Note how in blender 2.7x the space was called TOOLS but now it is called UI. The snippet above thus makes the code compatible for both blender 2.7x and 2.8x. I will say, try to contemplate that the actual UI workflows have changed too. Don’t just try to cram your UI into the closest place as before just for the sake of consistency.

Place your UI where it makes the most sense, and is consistent with new Blender 2.8 workflows.

Panel and menu name changes

In addition to region_type and space_type name changes, panels themselves have also changed in some cases. For instance, in 2.7x to append to the materials panel you would write bpy.types.Cycles_PT_context_material.append(my_ui_code) but now this has been renamed to bpy.types.CYCLES_PT_context_material.append(my_ui_code)  and bpy.types.EEVEE_MATERIAL_PT_context_material.append(my_ui_code) depending on your set render engine (note how case matters).

Remember, you can always go into the python console and use the autocomplete tool against bpy.types. Better yet, find an existing panel that is in the spot, and right click-edit script to get the UI code for that draw element. Looking higher up in this file will reveal the name of the panel you are looking for (shown below).

Want to make your panel-appending code work in both Blender 2.7 and 2.8? Then this is the codeblock for you:

if hasattr(bpy.types, "Cycles_PT_context_material"):
    bpy.types.Cycles_PT_context_material.append(my_ui_code)
elif hasattr(bpy.types, "CYCLES_PT_context_material"):
    bpy.types.CYCLES_PT_context_material.append(my_ui_code)
    bpy.types.EEVEE_MATERIAL_PT_context_material.append(my_ui_code)

Note again how I’m not doing blanket checks for bpy.app.version >= (2, 80), but directly checking whether the thing I want actually exists. See also this page for more details on best practices around making these UI change updates.

Pretty self explanatory. Not only are nearly all icons desaturated (or at least, reduced to a single color), several have been renamed, removed, or added. You can quickly this by enabling your code and navigating to your UI. Then, you can look into the console for errors about a given ICON not found.

The more thorough way to verify this would be to text search in your code for icon= and check each icon reference exists in the latest blender 2.8 builds. The Developer: Icon viewer addon is your friend (source of screenshots below)!

Changed icon designs and purpose

Even icons with unchanged names in 2.8 have an entirely new designs, so verify that it still makes sense to use it! Some specific examples I ran into:

• Now missing: LOAD_FACTORY, closest but non-exact replacement for my state-saving use case was DISK_DRIVE.
• Now missing: ZOOMIN, where ADD is the closest replacement
• Icons like COLOR_RED and COLOR_GREEN still exist, but are now just the letters R and G instead of the actual colors. Where I was previously using the color to indicate “good” vs “issue”, the newer icons don’t really give that impression. Thus, for my 2.8 code I switched to use checkmark (FILE_TICK) and X instead. Your own use case will vary.

While I normally advocate for avoiding blanket version checks via bpy.app.version, in this case it is appropriate. In the example above where ZOOMIN icon exists in blender 2.7, and ADD in 2.8 I could write the code icon="ZOOMIN" if bpy.app.version < (2, 80) else "ADD".

One final piece to call out – blender has a much simpler, modern design now. Many places were icons existed before now only show text. Consider following suit and not shoving icons into your UI for the sake of having an icon!

Allowed bl_idname for panels and menus

Update as of March 27, 2019: While class name registration is still not enforced, Blender has started to enforce the names of bl_idname’s for panels, menus, and UI Lists (and likely more).

• See the error “…doesn’t contain ‘_MT_’ with prefix & suffix”? Rename your menu bl_idname to be e.g. AAA_MT_menu_name (menus are the row-based popups you find in the interface, such as the info > file dropdown)
• See the error “…doesn’t contain ‘_PT_’ with prefix & suffix”? Rename your panel bl_idname to be e.g. AAA_PT_panel_name (panels are persistent areas within the interface, such as Transform section in the 3D view shelf)
• See the error “…doesn’t contain ‘_UL_’ with prefix & suffix”? Rename your UI List bl_idname to be e.g. AAA_UL_panel_name (this is the list-like, scrollbar object you can place inside a panel, such as the list of materials on an object)
• See the error “…doesn’t have upper case alpha-numeric prefix”? Rename your menu (or panel or UI list) bl_idname from aaa_MT_name to AAA_MT_name

Class name restrictions

Though no longer longer strictly enforced, the following is still best practice. Not following this could also lead to errors in the future (source). In short, follow these class naming practices: AAA_BB_cc where AAA is a typically the space this class will exist (e.g. VIEW3D) or is a common, uppercase abbreviation used across all of a single addon. BB is one of the 2 uppercase letters in the list below. Finally, cc is a lower-case name which describes this class, using underscores to separate words.

• OT: Operators, as in the actions you make as a user and the buttons found in the interface.
• PT: Panels, such as those sections in the properties screen, or a 3D view toolshelf tab.
• MT: Menus, such as the dropdown that appears after clicking the file button
• UL: UI Lists, such as the list of materials on an object or the list of particle systems applied.
• HT: Header of a window, top bar that makes up the File, Edit, Redner.. etc window of the Info screen.
• Property groups no specific naming convention, but PascalCaseIsEncouraged.

The “regex” way of describing this notation would be [A-Z][A-Z0-9_]*_MT_[A-Za-z0-9_]+ (source), but in more layman’s terms means a capitalized abbreviation, one of the 2-letter capitalized codes above, and then a fitting lowercase name, all joined together via underscores (preferred) or dashes.

Example usage

Say my “Smooth Models Addon” (or SMA) has an add smooth monkey operator. An appropriate name could then be class SMA_OT_smooth_monkey_add(bpy.types.Operator). A menu (dropdown/modal popup) holding the individual operators of my addon might be written as class SMA_MT_smooth_objects(bpy.types.Menu) and a panel in the tools tab of the 3D view might be  class SMA_PT_smooth_objects(bpy.types.Panel). Alternatively, Blender source code typically assigns a prefix based on the area of blender for which the operator pertains. For example, an operator affecting poses with lead with POSE_OT_.

Some additional minor changes which the console will again make readily evident include the change of layout.split(percentage=0.5) → layout.split(factor=0.5). If you want your UI code to work in both 2.8 and 2.8, then this utility could be helpful:

def layout_split(layout, factor=0.0, align=False):
    """Intermediate method for pre and post blender 2.8 split UI function"""
    if not hasattr(bpy.app, "version") or bpy.app.version < (2, 80):
        return layout.split(percentage=factor, align=align)
    return layout.split(factor=factor, align=align)

Note that some developers may choose to simply have different UI files for 2.7 and 2.8, and import accordingly. If you have enough changes to make, such as utilizing multi-column layouts, that may make more sense. I do end up checking the blender version here, but while supporting super old blender versions (predating the bpy.app.version api).