Review Blender 5.0 Python API

Live stream set for 2025-12-07 at 14:00:00 Eastern

Ask questions in the live chat about any programming or lifestyle topic.

This livestream will be on YouTube or you can watch below.

Blender 5.0 Python API: Key Changes and How to Work with Annotations and Grease Pencil

Blender 5.0 introduces significant updates to the Python API, affecting how developers interact with Blender’s scripting interface. These changes impact several systems, including annotations, Grease Pencil, node handling, and more. In this post, we’ll break down the major changes and provide guidance on how to adapt to them in your scripts, particularly focusing on annotations and Grease Pencil.

Blender 5.0 Python API – Key Changes and Summary

Blender 5.0 introduces many significant updates and changes to its Python API. Here’s a summary of the major changes across various areas:

1. Breaking Changes

• Removal of unsupported access to runtime-defined properties storage data: bpy.props-defined properties no longer support direct access through dict-like syntax. Accessing properties like bpy.context.scene['cycles'] is no longer possible.
• New methods get_transform and set_transform: These allow users to access and manipulate properties without directly modifying storage data, improving performance.
• Read-only properties: Properties can now be defined as read-only using a new READ_ONLY flag. Having only a getter without a setter makes a property read-only.
• Property handling and object manipulation: Accessing properties without triggering callbacks is no longer directly supported. Developers may need to restructure their code or use custom data storage to bypass property handling.

2. New Features & Improvements

• New get_transform and set_transform methods: These are specifically designed to be more efficient than older getter/setter methods, enabling faster updates and changes.
• Extensions and Python Code Update: When working with old property access, now you’ll need to use methods like property_unset instead of using the dict-like access.
• Bundled modules now private: Several internal Blender modules like bl_console_utils and bl_rna_utils are now private and should not be used by scripts.

3. Renaming of API Elements

• Grease Pencil to Annotation: Blender has renamed several Grease Pencil elements to Annotation elements for clarity and consistency. For example, bpy.types.GreasePencil is now bpy.types.Annotation, and bpy.data.grease_pencils is now bpy.types.annotations.
• The stroke and frame structures for annotations are also renamed: For example, bpy.types.GPencilStroke is now bpy.types.AnnotationStroke.
• Other renamed properties: Several properties were renamed to reflect the new structure, including MovieClip.grease_pencil to MovieClip.annotation, and Scene.grease_pencil to Scene.annotation.

4. Deprecated Features and Removal

• Deprecated BGL API removed: The old BGL API used for OpenGL-based drawing has been fully removed.
• Removed features: Certain properties in the EEVEE render engine have been moved or renamed. For example, scene.eevee.gtao_distance is now part of the view_layer.
• Deprecated compositor nodes: Some deprecated compositor nodes were removed, including combine and separate nodes.
• Alembic and USD export changes: There were changes and removal of deprecated options for both Alembic and USD export operators.

5. New Additions and API Enhancements

• Native support for buffer protocols in mathutils: This update improves the handling of mathutils types like Vector by switching to float32 from float64 for better performance.
• Node system updates: The compositor node interface has been simplified. For example, the Gamma node was replaced by its shader node counterpart.
• Point cache and geometry improvements: The PointCache no longer has a compression property; caches are now always compressed.

6. UI, Rendering, and Miscellaneous Updates

• UI changes: Certain theme properties related to UI widgets were removed or renamed, like navigation_bar and tab_active.
• Rendering updates: The render system now accepts optional frame_start and frame_end arguments in the render.render() operator.
• Logging updates: Blender 5.0 introduces new logging features, including the ability to log context members during temporary overrides.

7. Working with Annotations and Grease Pencil in Blender 5.0

The Annotations and Grease Pencil API has undergone major changes in Blender 5.0, including:

• Annotation Strokes: The AnnotationStroke objects replace the old Grease Pencil strokes.
• Layer & Frame Management: Creating annotation layers and frames follows a new API structure, improving the organization and management of strokes.

Creating and Manipulating Annotations & Grease Pencil in Blender 5.0

In Blender 5.0, all Grease Pencil-related features have been moved to annotations. This allows for cleaner, more flexible scripting and better performance when working with strokes and layers. Here’s how you can create and manipulate annotations using the updated API.

import bpy
import sys

# Define the name for our new Grease Pencil object
gp_name = "GP_Minimal_Working"

try:
    # --- 1. SETUP: Create the Grease Pencil Object ---
    gp_data = bpy.data.grease_pencils.new(gp_name)
    gp_object = bpy.data.objects.new(gp_name, gp_data)
    bpy.context.collection.objects.link(gp_object)

    bpy.context.view_layer.objects.active = gp_object
    gp_object.select_set(True)

    layer = gp_data.layers.new("Test_Layer", set_active=True)
    frame = layer.frames.new(0)
    drawing = frame.drawing

    # --- 2. STROKE CREATION 3 points, but they are all at (0, 0, 0) ---
    drawing.add_strokes([3]) 
    
    # --- 3. SAVE ---
    bpy.ops.wm.save_as_mainfile(filepath="gp_minimal.blend", check_existing=False)

except Exception as e:
    print(f"\nFATAL EXECUTION ERROR: {e}", file=sys.stderr)
    sys.exit(1)
  

This code demonstrates how to:

• Create a new annotation object.
• Add a new annotation layer.
• Add a frame to the annotation layer.
• Create a stroke and set its points to create shapes or annotations in 3D space.

New Features in Blender 5.0 API: Performance Improvements

Blender 5.0 introduces new methods like get_transform and set_transform that replace traditional getter and setter functions. These new methods are faster, providing significant performance improvements, especially when dealing with transformations and data manipulation. You should use these methods where possible for better performance in your scripts.

Updated Node System and Geometry Nodes

Blender 5.0 has overhauled the node system. Some nodes were deprecated or replaced, such as the CompositorNodeGamma being replaced by ShaderNodeGamma. Additionally, the geometry nodes API has been updated to simplify the creation and manipulation of nodes in node trees. These changes improve the usability and flexibility of the node-based systems in Blender.

Handling Deprecated and Removed Features in Blender 5.0

As part of the transition to Blender 5.0, several deprecated features have been removed or updated. Notably, the compositor nodes and bpy.types.GreasePencil (now renamed to bpy.types.Annotation) have undergone major changes. Scripts relying on these features will need to be updated to work with the new API. Furthermore, certain bundled Python modules have been made private and should no longer be used by scripts.

📸 Screenshots & Screencast

Resources and Further Learning

• Learning Python – A beginner-friendly guide to learning Python programming.
• Mastering Blender Python API – A comprehensive guide to mastering Blender scripting with Python.

Learning Python Course – An in-depth online course to help you master Python programming from scratch.

Conclusion

Blender 5.0 introduces significant improvements and changes to its Python API, particularly with annotations and Grease Pencil (now renamed to Annotations). By updating your code to reflect these changes, you can ensure smoother and more efficient development. The new get_transform and set_transform methods, alongside the updated node system and property access methods, provide substantial performance benefits. Be sure to adapt to the new standards to get the most out of Blender 5.0’s Python API.