Blender Python

Blender Python API Reference

Targets Blender 5.0 and Blender 5.1. Python 3.11 (5.0) and 3.13 (5.1).

General Principles

Module structure. The top-level bpy module exposes sub-modules: bpy.context (read-only state), bpy.data (all data-blocks), bpy.ops (operators), bpy.types (RNA type definitions), bpy.props (property declarations), bpy.app (version/paths/handlers/timers), bpy.utils (registration helpers), bpy.msgbus (message bus subscriptions), bpy.path (Blender path utilities). Standalone modules include bmesh, mathutils, gpu, gpu_extras, freestyle, aud, imbuf, bl_math, bpy_extras, idprop, and blf.

Data-block model. All persistent data lives as data-blocks in bpy.data collections (objects, meshes, materials, etc.). Data-blocks inherit from bpy.types.ID. Maximum name length is 255 bytes. Loading a new blend file replaces all data-blocks — never hold long-lived Python references across file loads. Data-blocks are reference-counted; use orphans_purge() to remove unused ones.

RNA and IDProperty distinction. RNA is Blender's runtime type system — it auto-generates the Python API (bpy.types). Properties declared via bpy.props are RNA properties with type safety and UI integration. IDProperties are arbitrary key/value storage accessed dict-style (obj["key"]). In 5.0, RNA property storage is fully separated from IDProperty storage — bpy.props definitions no longer write to IDProperty dicts. Code that relied on reading bpy.props values via dict access must be updated. See [bpy-props](references/bpy-props.md) and [idprop](references/idprop.md).

Operator context requirements. Operators (bpy.ops) act on bpy.context. Calling an operator in the wrong context raises RuntimeError. Always check bpy.ops...poll() first or handle the exception. Use context.temp_override() to provide the correct context programmatically. Execution context can be specified as the first argument: 'EXEC_DEFAULT' (skip invoke, just execute) or 'INVOKE_DEFAULT' (call invoke first). Prefer direct data API over operators when possible.

Registered class lifecycle. Custom types (Operator, Panel, Menu, PropertyGroup) must inherit from the correct bpy.types base and be registered via bpy.utils.register_class(). Registration must happen inside register() functions, not at module level. Unregistration must reverse the exact order. Failing to unregister causes "already registered as a subclass" errors on re-enable. If a class defines a register classmethod, it is called automatically during registration.

Undo system caveats. Undo invalidates all bpy.types.ID references — Python objects pointing to Blender data become stale. Never cache data-block references long-term. Re-query from bpy.data by name or use session UIDs. Re-allocation (adding items to collections) can also invalidate existing references. Modal operators that store references to Blender data must re-acquire them after any operation that triggers undo.

IDProperty storage separation (5.0). Properties defined via bpy.props are no longer accessible through dict-like syntax on data-blocks. Custom properties and RNA properties occupy separate storage. Use get_transform/set_transform callbacks instead of get/set when you only need value mapping — they are several times faster. Blend files from 4.5 and earlier get custom data IDProperties duplicated into system ones during versioning.

Evaluated vs original data. Original data (bpy.data.objects[...]) is user-editable with no modifiers applied. Evaluated data (via depsgraph.id_eval_get() or obj.evaluated_get(depsgraph)) has all modifiers, constraints, and drivers applied. For mesh objects, obj_eval.data gives the fully modified mesh. Edits must target original data — changes to evaluated copies are discarded. Use depsgraph.update() to force re-evaluation after changes.

Script execution environments. Scripts run in the Text Editor (Run Script), the Python Console (interactive REPL), startup scripts (scripts/startup/), registered addons/extensions, or background mode (blender --background). Background mode does not build ViewLayer dependency graphs by default and has no UI areas — context.area is None. The console provides autocompletion; the text editor supports templates. CLI flags --python, --python-expr, and --python-console allow running scripts from the command line.

Compositor migration (5.0). The compositor uses standalone node groups: scene.compositing_node_group replaces the removed scene.node_tree. Compositor node types are renamed from CompositorNode* to ShaderNode* equivalents. The Composite output node is replaced by GroupOutput. See [compositor-nodes](references/compositor-nodes.md).

Slotted actions (5.0). The animation system uses slotted Actions. An Action contains Slots (animation targets), Layers, and Strips with Channelbags that hold FCurves. The legacy action.fcurves and action.groups properties are removed. keyframe_insert() still works unchanged. See [animation-actions](references/animation-actions.md).

BGL removed (5.0). The bgl module (OpenGL wrappers) is fully removed. All GPU drawing must use the gpu module. Image.bindcode is removed — use gpu.texture.from_image(). EEVEE's engine identifier is 'BLENDER_EEVEE' (was 'BLENDER_EEVEE_NEXT').

Routing Table

Core API

| Query is about... | Read | |---|---| | bpy.context, active object, selected objects, mode, temp_override, evaluated depsgraph access | [bpy-context](references/bpy-context.md) | | bpy.data, data-block collections, creating/removing data-blocks, batch_remove, orphans_purge, library linking/appending | [bpy-data](references/bpy-data.md) | | bpy.types hierarchy, Object/Scene/Collection/ViewLayer types, ID base class, compositing_node_group | [bpy-types-core](references/bpy-types-core.md) | | bpy.props, property types, PropertyGroup, property options, READ_ONLY, get_transform/set_transform, update callbacks | [bpy-props](references/bpy-props.md) | | IDProperties, dict-like access on data-blocks, id_properties_ui, custom properties, type mapping, 5.0 storage separation | [idprop](references/idprop.md) | | bpy.ops, calling operators, return values, execution_context, poll, operator search | [bpy-ops](references/bpy-ops.md) | | bpy.app, version info, paths, cachedir, is_job_running, handlers list, build info | [bpy-app](references/bpy-app.md) | | bpy.utils, class registration, previews, script paths, expose_bundled_modules, VFX library access | [bpy-utils](references/bpy-utils.md) | | bpy.msgbus, subscribe_rna, publish_rna, message bus subscriptions, path_resolve for keys | [bpy-msgbus](references/bpy-msgbus.md) |

Operators & UI

| Query is about... | Read | |---|---| | Writing custom operators, bl_idname, bl_options, execute/invoke/check, operator properties, menu/keymap registration | [operators-custom](references/operators-custom.md) | | Modal operators, modal() method, event types/values, mouse coords, timers, draw callbacks, header_text_set | [operators-modal](references/operators-modal.md) | | Panels, bl_space_type/bl_region_type/bl_category, sub-panels, draw/poll, UILayout basics (row, column, box, split, prop, operator) | [panels-ui](references/panels-ui.md) | | Advanced UI: prop_search, template_ID, template_list, UIList subclass, filter_items, icon previews, dynamic enums, popover, menu_pie | [ui-layout-advanced](references/ui-layout-advanced.md) | | Gizmos, GizmoGroup, built-in gizmo types (arrow, dial, move, cage, primitive), target_set_prop/handler, matrix_basis | [gizmos](references/gizmos.md) |

Addon / Extension Development

| Query is about... | Read | |---|---| | Addon structure, bl_info, register/unregister, multi-file addons, importlib.reload, class registration order | [addon-structure](references/addon-structure.md) | | Extensions system, blender_manifest.toml schema, local/remote repos, CLI build/install, permissions, publishing | [extensions-system](references/extensions-system.md) | | Addon preferences, AddonPreferences, bl_idname = __package__, accessing prefs, bl_system_properties_get, keymap registration | [addon-preferences](references/addon-preferences.md) | | Porting from 4.x to 5.0/5.1, breaking changes, before/after code, migration patterns | [porting-from-4x](references/porting-from-4x.md) |

Mesh & Geometry

| Query is about... | Read | |---|---| | Mesh data: vertices, edges, polygons, loops, corner_verts/corner_edges, attribute API, foreach_get/set, UVs, vertex groups, shape keys | [mesh-data](references/mesh-data.md) | | Mesh advanced: calc_smooth_groups, validate, calc_normals_split, from_pydata, calc_loop_triangles, domain_size | [mesh-advanced](references/mesh-advanced.md) | | BMesh: bmesh.new, from_edit_mesh/from_mesh/to_mesh/free, verts/edges/faces/loops, layers, ensure_lookup_table, bmesh.ops | [bmesh](references/bmesh.md) | | Curves data: Curves type, curve types (POLY/BEZIER/NURBS/CATMULL_ROM), resize_curves/remove_curves/set_types, point attributes | [curves-data](references/curves-data.md) | | Geometry Nodes API: modifier socket access, output attributes, GeometrySet, baking, viewer node, node tool idname | [geometry-nodes-api](references/geometry-nodes-api.md) |

Materials & Nodes

| Query is about... | Read | |---|---| | Shader nodes: use_nodes, node_tree, nodes.new(), type strings, input/output access, default_value, links.new, group nodes | [shader-nodes](references/shader-nodes.md) | | Compositor nodes: compositing_node_group, CompositorNode→ShaderNode rename table, GroupOutput replaces Composite, file_output_items | [compositor-nodes](references/compositor-nodes.md) | | Materials API: creating materials, use_nodes, Principled BSDF inputs, image textures, material slots, World material | [materials-api](references/materials-api.md) | | Node tree interface: new_socket, new_panel, socket_type enum, items_tree, Group Input/Output nodes | [node-tree-interface](references/node-tree-interface.md) | | Node closures and bundles: Combine/Separate Bundle, repeat zones, inline_shader_nodes API for render engines | [node-closures-bundles](references/node-closures-bundles.md) |

Animation

| Query is about... | Read | |---|---| | Actions (slotted system): action.slots, ActionSlot, layers, strips, channelbags, fcurves.new/ensure, fcurve_ensure_for_datablock | [animation-actions](references/animation-actions.md) | | Keyframes, FCurves, drivers: keyframe_insert/delete, keyframe_points, handle types, FCurve modifiers, driver expressions, variables | [keyframes-drivers](references/keyframes-drivers.md) | | NLA: nla_tracks, strips, blend types, extrapolation, influence, push_down, baking | [nla](references/nla.md) | | Handlers and timers: frame_change_pre/post, depsgraph_update, load_pre/post, @persistent, bpy.app.timers | [handlers-timers](references/handlers-timers.md) |

Rendering & GPU

| Query is about... | Read | |---|---| | Render API: RenderEngine subclass, render/viewupdate/viewdraw, RenderResult/Layer/Pass, engine ID renames, pass name renames | [render-api](references/render-api.md) | | GPU module: gpu.shader.from_builtin, create_from_info, GPUShader/GPUTexture/GPUBatch/GPUVertBuf, gpu.state, gpu.matrix, POLYLINE/POINT variants | [gpu-module](references/gpu-module.md) | | GPU extras: batch_for_shader, draw_texture_2d, draw_circle_2d, batch creation workflow | [gpu-extras](references/gpu-extras.md) | | GPU offscreen: GPUOffScreen creation, bind/unbind, draw_view3d, depth format deprecations, render-to-texture | [gpu-offscreen](references/gpu-offscreen.md) | | GPU drawing: draw_handler_add, handler removal, 3D/2D drawing workflows, color space handling | [gpu-drawing](references/gpu-drawing.md) | | Text drawing: blf module, font loading, size/position/draw/color, shadow, rotation, clipping, word wrap, bind_imbuf | [blf](references/blf.md) |

Math & Utilities

| Query is about... | Read | |---|---| | mathutils: Vector, Matrix, Quaternion, Euler, Color, arithmetic, freeze(), buffer protocol (float32) | [mathutils](references/mathutils.md) | | mathutils.geometry: intersect_*, barycentric_transform, tessellate_polygon, convex_hull_2d, distance_point_to_plane | [mathutils-geometry](references/mathutils-geometry.md) | | KDTree, BVHTree, noise: spatial queries, find/find_n/find_range, ray_cast, find_nearest, overlap, noise functions | [mathutils-spatial](references/mathutils-spatial.md) | | bl_math: clamp, lerp, smoothstep, pingpong, round_to_even | [bl-math](references/bl-math.md) | | bpy.path: abspath (// resolution), relpath, clean_name, ensure_ext, native_pathsep | [bpy-path](references/bpy-path.md) | | bpy_extras: view3d_utils, io_utils (ImportHelper/ExportHelper), mesh_utils, object_utils, anim_utils | [bpy-extras](references/bpy-extras.md) |

Scene & Objects

| Query is about... | Read | |---|---| | Object transforms: matrix_world/local/basis/parent_inverse, decompose, delta transforms, constraints, parenting, to_mesh | [objects-transforms](references/objects-transforms.md) | | Collections, scene management: Collection hierarchy, objects.link/unlink, all_objects, layer_collection, scene.ray_cast, cursor | [collections-scene](references/collections-scene.md) | | Dependency graph: evaluated_depsgraph_get, id_eval_get, object_instances, DepsgraphObjectInstance, updates, original vs evaluated | [depsgraph](references/depsgraph.md) | | Armatures: bones, edit_bones, PoseBone, BoneCollection API, select properties, Geometry Attribute constraint, mode switching | [armatures](references/armatures.md) |

I/O & Pipeline

| Query is about... | Read | |---|---| | Import/export operators: glTF, FBX, OBJ, STL, Alembic — key parameters, batch export, format selection | [import-export](references/import-export.md) | | USD pipeline: USD import/export, Python export hooks, pxr module access, stage traversal | [usd-pipeline](references/usd-pipeline.md) | | File I/O: bpy.ops.wm.open_mainfile/save_mainfile, library overrides, asset system, bpy.data.libraries, forward compatibility | [file-io](references/file-io.md) |

Image & Audio

| Query is about... | Read | |---|---| | imbuf module: ImBuf creation, pixel access, load/save, format conversion, gpu.texture.from_image() | [imbuf](references/imbuf.md) | | aud module: Device, Sound, Handle, playback, filters, sequencing | [aud](references/aud.md) |

Grease Pencil & Annotations

| Query is about... | Read | |---|---| | Grease Pencil v3: layers, frames, drawings, add_strokes, attribute-based point access, stroke materials | [grease-pencil](references/grease-pencil.md) | | Annotations: annotation layers/frames/strokes, rename table from legacy GP types | [annotations](references/annotations.md) |

Freestyle

| Query is about... | Read | |---|---| | Freestyle types: type hierarchy, Nature constants, iterators, Interface0D/1D, ViewEdge, StrokeVertex | [freestyle-types](references/freestyle-types.md) | | Freestyle scripting: pipeline (Selection→Chaining→Splitting→Sorting→Creation), predicates, shaders, style modules | [freestyle-scripting](references/freestyle-scripting.md) |

Video Sequence Editor

| Query is about... | Read | |---|---| | VSE strips: strip types, sequences.new_* methods, strip properties, channels, transform, proxy | [sequencer-strips](references/sequencer-strips.md) | | VSE effects and retiming: effect strips, speed control, retiming keys, time property renames | [sequencer-effects-retiming](references/sequencer-effects-retiming.md) |

Scripting Environment

| Query is about... |

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: devanshutak25
• Source: devanshutak25/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.