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

Blender	Python	VFX Platform
3.x	3.10	2023
4.0	3.10	2023
4.1	3.11	2024
4.2 LTS	3.11	2024
4.3	3.11	2024
4.4	3.11	2024
4.5 LTS	3.11	2024
5.0	3.11	2025
5.1	3.13	2026

Critical Breaking Changes Summary

Change	Removed In	Migration
Context override dicts on `bpy.ops`	4.0	`context.temp_override()`
`MeshEdge.bevel_weight` / `.crease`	4.0	`mesh.attributes.get("bevel_weight_edge")`
`obj.face_maps`	4.0	Integer face attributes
`bone.layers[i]` / `pose.bone_groups`	4.0	`bone.collections`
`NodeTree.inputs/outputs.new()`	4.0	`NodeTree.interface.new_socket()`
Principled BSDF socket names	4.0	Renamed: `Subsurface Weight`, `Specular IOR Level`, etc.
`3D_UNIFORM_COLOR` shader name	4.0	`POLYLINE_UNIFORM_COLOR`
Python OBJ/PLY importers	4.0	`bpy.ops.wm.obj_import/export`
`Mesh.use_auto_smooth`	4.1	`Mesh.corner_normals` + Smooth by Angle modifier
Light probe `CUBEMAP`/`PLANAR`/`GRID`	4.1	`SPHERE` / `PLANE` / `VOLUME`
`mat.cycles.displacement_method`	4.1	`mat.displacement_method`
`blender_manifest.toml` required	4.2	Replace `bl_info` dict with TOML manifest
EEVEE → `BLENDER_EEVEE_NEXT`	4.2	Check identifier string
`bpy.types.AttributeGroup`	4.3	`AttributeGroupMesh`, `AttributeGroupPointCloud`, etc.
Grease Pencil API rewrite	4.3	Complete API rewrite; see migration guide
EEVEE legacy properties	4.3	40+ properties removed
Subclass `__init__` must call `super()`	4.4	Forward `args, *kwargs` to parent
`bpy.types.Sequence` → `bpy.types.Strip`	4.4	Rename all Sequence references
Slotted Actions system	4.4	`action.layers[0].strips[0].channelbag()`
`bgl` module	5.0	`gpu` module (MANDATORY)
`scene['cycles']` dict access	5.0	Attribute access on RNA properties
`scene.node_tree` (compositor)	5.0	`scene.compositing_node_group`
`brush.sculpt_tool`	5.0	`brush.sculpt_brush_type`
`action.fcurves` legacy API	5.0	Slotted Actions channelbag API
VSE `end_frame`	5.0	`length` property
VSE strip time property renames	5.1	`frame_final_duration` → `duration`, etc. (removal in 6.0)
Python 3.13	5.1	Check stdlib changes

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

About this skill