Blender Core Versions

Blender Core Versions: Python API Version Matrix

1. Quick Reference

Version Detection

# Blender 3.x / 4.x / 5.x: ALWAYS use tuple comparison for version checks
import bpy
major, minor, patch = bpy.app.version  # e.g., (4, 2, 0)

# Version-safe conditional
if bpy.app.version >= (4, 0, 0):
    # Blender 4.0+ code path
    pass
else:
    # Blender 3.x fallback
    pass

See references/methods.md for complete version detection API.

Python Version Matrix

Critical Breaking Changes Summary

2. Essential Patterns

Version-Safe Conditionals

ALWAYS use bpy.app.version tuple comparison. NEVER parse bpy.app.version_string.

# Blender 3.x / 4.x / 5.x: Version-safe conditional pattern
import bpy

if bpy.app.version >= (5, 0, 0):
    # Blender 5.0+ code
    comp_tree = scene.compositing_node_group
elif bpy.app.version >= (4, 0, 0):
    # Blender 4.0–4.x code
    comp_tree = scene.node_tree
else:
    # Blender 3.x code
    comp_tree = scene.node_tree

Feature Detection Pattern

ALWAYS prefer hasattr() checks over version comparisons when testing for a specific API.

# Blender 3.x / 4.x / 5.x: Feature detection pattern
import bpy

# Prefer feature detection over version check
if hasattr(bpy.types, "AttributeGroupMesh"):
    # Blender 4.3+ — type-specific attribute groups
    pass
else:
    # Blender < 4.3 — generic AttributeGroup
    pass

# For method existence
mesh = bpy.context.active_object.data
if hasattr(mesh, "corner_normals"):
    # Blender 4.1+ — use corner_normals
    normals = mesh.corner_normals
else:
    # Blender < 4.1 — use legacy auto_smooth
    mesh.use_auto_smooth = True

Context Override Pattern

# Blender 3.x: LEGACY context override (BROKEN in 4.0+)
override = {"object": obj, "active_object": obj}
bpy.ops.object.modifier_apply(override, modifier="Boolean")

# Blender 4.0+: temp_override (REQUIRED)
with bpy.context.temp_override(object=obj, active_object=obj):
    bpy.ops.object.modifier_apply(modifier="Boolean")

# Version-safe wrapper
def apply_modifier(obj, modifier_name):
    if bpy.app.version >= (4, 0, 0):
        with bpy.context.temp_override(object=obj, active_object=obj):
            bpy.ops.object.modifier_apply(modifier=modifier_name)
    else:
        override = {"object": obj, "active_object": obj}
        bpy.ops.object.modifier_apply(override, modifier=modifier_name)

Node Group Interface Pattern

# Blender 3.x: LEGACY (BROKEN in 4.0+)
node_group.inputs.new("NodeSocketFloat", "Width")
node_group.outputs.new("NodeSocketGeometry", "Geometry")

# Blender 4.0+: interface API (REQUIRED)
node_group.interface.new_socket(
    name="Width", in_out='INPUT', socket_type='NodeSocketFloat'
)
node_group.interface.new_socket(
    name="Geometry", in_out='OUTPUT', socket_type='NodeSocketGeometry'
)

EEVEE Identifier Pattern

# Blender 3.x: 'BLENDER_EEVEE'
# Blender 4.2–4.x: 'BLENDER_EEVEE_NEXT'
# Blender 5.0+: 'BLENDER_EEVEE' (changed back)
import bpy

def get_eevee_identifier():
    if bpy.app.version >= (5, 0, 0):
        return 'BLENDER_EEVEE'
    elif bpy.app.version >= (4, 2, 0):
        return 'BLENDER_EEVEE_NEXT'
    else:
        return 'BLENDER_EEVEE'

scene = bpy.context.scene
scene.render.engine = get_eevee_identifier()

Extension Manifest Pattern

# Blender 3.x / 4.0 / 4.1: bl_info dict in __init__.py
bl_info = {
    "name": "My Addon",
    "blender": (4, 0, 0),
    "category": "Object",
    "version": (1, 0, 0),
    "description": "My addon description",
}

# Blender 4.2+: blender_manifest.toml (REQUIRED for extensions)
# File: blender_manifest.toml
# schema_version = "1.0.0"
# id = "my_addon"
# version = "1.0.0"
# name = "My Addon"
# tagline = "Short description up to 64 chars"
# maintainer = "Dev Name <email@example.com>"
# type = "add-on"
# blender_version_min = "4.2.0"

GPU Drawing Pattern (BGL → gpu Migration)

# Blender 3.x: bgl module (BROKEN in 5.0)
import bgl
bgl.glEnable(bgl.GL_BLEND)
bgl.glLineWidth(2)
shader = gpu.shader.from_builtin('3D_UNIFORM_COLOR')

# Blender 4.0+: gpu module (REQUIRED for 5.0+)
import gpu
gpu.state.blend_set('ALPHA')
gpu.state.line_width_set(2.0)
shader = gpu.shader.from_builtin('POLYLINE_UNIFORM_COLOR')

# ALWAYS restore gpu state at end of draw callbacks
gpu.state.blend_set('NONE')
gpu.state.line_width_set(1.0)

Compositor Access Pattern

# Blender 3.x / 4.x: scene.node_tree
scene = bpy.context.scene
scene.use_nodes = True
comp_tree = scene.node_tree

# Blender 5.0+: compositing_node_group
scene = bpy.context.scene
comp_tree = bpy.data.node_groups.new("MyComp", 'CompositorNodeTree')
scene.compositing_node_group = comp_tree

Slotted Actions Pattern (4.4+)

# Blender 3.x / 4.0–4.3: Legacy action.fcurves
action = bpy.data.actions.new("MyAction")
fcurve = action.fcurves.new(data_path="location", index=0)

# Blender 4.4+: Slotted Actions (legacy removed in 5.0)
action = bpy.data.actions.new("MyAction")
slot = action.slots.new()
layer = action.layers.new(name="Layer")
strip = layer.strips.new(type='KEYFRAME')
channelbag = strip.channelbags.new(slot=slot)
fcurve = channelbag.fcurves.new(data_path="location", index=0)

3. Common Operations: Migration Checklists

3.x → 4.0 Migration Checklist

• Replace ALL context override dicts with context.temp_override()
• Replace mesh.edges[i].bevel_weight with mesh.attributes.get("bevel_weight_edge")
• Replace mesh.edges[i].crease with mesh.attributes.get("crease_edge")
• Replace obj.face_maps with integer face attributes
• Replace bone.layers[i] with bone.collections
• Replace pose.bone_groups with bone collections + colors
• Replace NodeTree.inputs/outputs.new() with NodeTree.interface.new_socket()
• Update Principled BSDF socket names (Subsurface → Subsurface Weight, etc.)
• Replace 3D_UNIFORM_COLOR with POLYLINE_UNIFORM_COLOR
• Replace Mesh.calc_normals() (removed, now auto-calculated)
• Replace Python OBJ/PLY IO with bpy.ops.wm.obj_import/export
• Remove filename params, use filepath instead
• Update anim_utils.bake_action() to use BakeOptions dataclass

4.0 → 4.1 Migration Checklist

• Remove mesh.use_auto_smooth and mesh.auto_smooth_angle
• Use mesh.corner_normals for normal access
• Use "Smooth by Angle" modifier for angle-based smoothing
• Rename light probe types: CUBEMAP→SPHERE, PLANAR→PLANE, GRID→VOLUME
• Move mat.cycles.displacement_method to mat.displacement_method
• Add type checking for foreach_set() calls (now raises TypeError)
• Rename sequencer filter SUBSAMPLING_3x3 → BOX
• Use socket identifiers instead of indices for dynamic sockets

4.1 → 4.2 Migration Checklist

• Create blender_manifest.toml for extension system
• Handle statically typed IDProperties (no implicit type changes)
• Update EEVEE identifier: BLENDER_EEVEE → BLENDER_EEVEE_NEXT
• Move scene.cycles.motion_blur_position to scene.render.motion_blur_position
• Move scene.eevee.use_motion_blur to scene.render.use_motion_blur
• Replace blend_method with surface_render_method
• Replace object.load_reference_image with object.empty_image_add
• Update compositor mask node properties: width→mask_width, height→mask_height

4.2 → 4.3 Migration Checklist

• Replace bpy.types.AttributeGroup usage with type-specific classes
• Migrate ALL Grease Pencil code to new API
• Remove references to EEVEE legacy properties (contact shadows, SSR, bloom, etc.)
• Update reroute node handling to use socket_idname property
• Do NOT assign embedded IDs to PointerProperty

4.3 → 4.4 Migration Checklist

• Add super().__init__(*args, **kwargs) to ALL Blender type subclasses
• Rename bpy.types.Sequence references to bpy.types.Strip
• Adopt Slotted Actions API for new animation code
• Update paint.brush usage (now read-only property)
• Ensure pos attribute uses F32 FLOAT for GPU polyline drawing

4.x → 5.0 Migration Checklist

• Remove ALL import bgl — replace with gpu module
• Replace scene['cycles'] dict access with attribute access
• Replace scene.node_tree with scene.compositing_node_group
• Replace brush.sculpt_tool with brush.sculpt_brush_type
• Replace legacy action.fcurves with Slotted Actions channelbag API
• Replace VSE end_frame with length
• Update EEVEE identifier from BLENDER_EEVEE_NEXT back to BLENDER_EEVEE
• Remove usage of bundled private modules (animsys_refactor, etc.)
• Replace Image.bindcode with gpu.texture.from_image()
• Replace gpu.types.GPUShader() constructor with gpu.shader.create_from_info()

5.0 → 5.1 Migration Checklist

• Replace sculpt.sample_color with paint.sample_color
• Update to Python 3.13 — check stdlib compatibility
• Prepare for VSE time property renames (deprecated, removed in 6.0): frame_final_duration → duration, frame_final_start → left_handle, etc.

4. Reference Links

• references/methods.md — Complete version detection API: bpy.app.version, bpy.app.version_string, bpy.app.version_cycle
• references/examples.md — Migration code examples for EACH version transition (3.x→4.0, 4.0→4.1, 4.1→4.2, 4.2→4.3, 4.3→4.4, 4.4→5.0, 5.0→5.1)
• references/anti-patterns.md — Common version migration mistakes with explanations

Official Documentation

• Blender 4.0 Python API Changes
• Blender 4.1 Python API Changes
• Blender 4.2 Python API Changes
• Blender 4.3 Python API Changes
• Blender 4.4 Python API Changes
• Blender 4.5 Python API Changes
• Blender 5.0 Python API Changes
• Blender 5.1 Python API Changes
• Blender API Compatibility Notes
• Blender API Change Log