Blender Agents Version Migrator

Blender Agent: Version Migrator

Systematic migration process for Blender Python code across major versions. This agent skill activates when migrating, porting, updating, or upgrading Blender Python scripts or addons between versions 3.x, 4.x, and 5.x.

Dependencies:

• blender-core-versions — version matrix, detection API, breaking changes
• blender-errors-version — error diagnosis for version-related failures

1. Quick Reference: Migration Paths

Supported Migration Paths

Migration Execution Order

For a 3.x → 5.x migration, ALWAYS apply changes in this exact order:

1. 3.x → 4.0 changes
2. 4.0 → 4.1 changes
3. 4.1 → 4.2 changes
4. 4.2 → 4.3 changes
5. 4.3 → 4.4 changes
6. 4.4 → 5.0 changes
7. 5.0 → 5.1 changes

NEVER skip intermediate versions. Each version removes APIs deprecated in prior versions.

2. Migration Agent Process

When migrating Blender Python code, follow these steps in order:

Step 1: Identify Source and Target Versions

# Determine current version compatibility from code signals
# Check for these indicators:
# - bl_info dict → 3.x / 4.0 / 4.1 addon
# - blender_manifest.toml → 4.2+ extension
# - import bgl → pre-5.0 code
# - context override dicts on bpy.ops → pre-4.0 code
# - mesh.use_auto_smooth → pre-4.1 code
# - NodeTree.inputs.new() → pre-4.0 code

Step 2: Scan for Affected APIs

Search the codebase for ALL patterns listed in the Find-and-Replace Tables (Section 3). Mark each occurrence with the version transition that affects it.

Step 3: Apply Changes Per Version Transition

Apply changes from the relevant migration checklists below. Process ONE version transition at a time.

Step 4: Update Metadata

• Replace bl_info with blender_manifest.toml if targeting 4.2+
• Update minimum version requirements
• Update any version checks in the code

Step 5: Validate

• Search for ANY remaining references to removed APIs
• Verify all import statements reference available modules
• Check that gpu.state is restored at end of draw callbacks
• Confirm super().__init__(*args, **kwargs) in all Blender type subclasses (4.4+)

3. Find-and-Replace Tables

3.x → 4.0 Replacements

4.0 → 4.1 Replacements

4.1 → 4.2 Replacements

4.2 → 4.3 Replacements

4.3 → 4.4 Replacements

4.x → 5.0 Replacements

5.0 → 5.1 Replacements

4. Decision Tree: Compatibility Shims vs Clean Migration

MIGRATION STRATEGY DECISION
│
├── Target SINGLE Blender version?
│   └── YES → Clean migration: remove ALL legacy code, use target API only
│
├── Target VERSION RANGE (e.g., 3.x + 4.x)?
│   ├── Range spans 3.x and 4.0+ ?
│   │   └── YES → Use version-safe wrappers with bpy.app.version checks
│   ├── Range spans 4.x and 5.0+ ?
│   │   └── YES → Use version-safe wrappers; NEVER import bgl at module level
│   └── Range within single major (e.g., 4.0–4.4)?
│       └── Use hasattr() feature detection for minor version differences
│
└── Target LATEST only (drop legacy)?
    └── Clean migration: target version API only, no compatibility code

When to Use Compatibility Shims

ALWAYS use compatibility shims when:

• The addon targets 2+ major Blender versions simultaneously
• The addon is distributed to users on different Blender versions

NEVER use compatibility shims when:

• The migration targets a single Blender version
• The code is an internal tool pinned to one Blender version

Compatibility Module Pattern

# compat.py: Version-safe compatibility layer
import bpy

BLENDER_4 = bpy.app.version >= (4, 0, 0)
BLENDER_41 = bpy.app.version >= (4, 1, 0)
BLENDER_42 = bpy.app.version >= (4, 2, 0)
BLENDER_43 = bpy.app.version >= (4, 3, 0)
BLENDER_44 = bpy.app.version >= (4, 4, 0)
BLENDER_5 = bpy.app.version >= (5, 0, 0)
BLENDER_51 = bpy.app.version >= (5, 1, 0)

def apply_modifier(obj, modifier_name):
    if BLENDER_4:
        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)

Conditional Import Pattern for BGL → gpu

# NEVER import bgl at module level in multi-version addons
import gpu

# For addons targeting 3.x–4.x (before 5.0 removal):
try:
    import bgl
    HAS_BGL = True
except ImportError:
    HAS_BGL = False  # Blender 5.0+

# ALWAYS use gpu module for new code regardless of version

5. EEVEE Identifier Migration

The EEVEE render engine identifier changed across versions. ALWAYS use this lookup:

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'

6. Extension System Migration (4.2+)

When migrating from legacy addon to extension system:

1. Create blender_manifest.toml in addon root
2. Remove bl_info dict from __init__.py
3. Set blender_version_min = "4.2.0" (or target minimum)
4. Add id matching the package directory name
5. Add tagline (max 64 chars, no trailing punctuation)
6. Add type = "add-on" or type = "theme"
7. Add network permissions if addon accesses internet: [permissions] → network = "Reason for access"
8. Add license = ["SPDX:GPL-3.0-or-later"] (or appropriate SPDX)

7. Critical Migration Rules

1. NEVER use import bgl in code targeting Blender 5.0+ — the module is REMOVED.
2. ALWAYS restore gpu.state to defaults at the end of every draw callback.
3. NEVER pass a dict as the first argument to bpy.ops in Blender 4.0+ — use context.temp_override().
4. ALWAYS add super().__init__(*args, **kwargs) to Blender type subclasses in 4.4+.
5. NEVER suppress DeprecationWarning — it hides migration signals.
6. NEVER use try/except AttributeError as a version check — use bpy.app.version or hasattr().
7. ALWAYS set POLYLINE_UNIFORM_COLOR shader uniforms: viewportSize and lineWidth.
8. ALWAYS migrate Grease Pencil code completely when targeting 4.3+ — partial migration breaks.
9. NEVER assign embedded IDs to PointerProperty in 4.3+.
10. ALWAYS check the deprecation timeline in blender-errors-version before using any API.

8. Reference Links

• references/methods.md — Complete API migration mappings organized by version transition
• references/examples.md — Before/after code examples for each migration path
• references/anti-patterns.md — Common 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
• Grease Pencil 4.3 Migration Guide