Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/devanshutak25/agent-skills --skill blender-pythonAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
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 and idprop.
Operator context requirements. Operators (bpy.ops) act on bpy.context. Calling an operator in the wrong context raises RuntimeError. Always check bpy.ops.<cat>.<op>.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.
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.
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 |
bpy.data, data-block collections, creating/removing data-blocks, batch_remove, orphans_purge, library linking/appending | bpy-data |
bpy.types hierarchy, Object/Scene/Collection/ViewLayer types, ID base class, compositing_node_group | bpy-types-core |
bpy.props, property types, PropertyGroup, property options, READ_ONLY, get_transform/set_transform, update callbacks | bpy-props |
IDProperties, dict-like access on data-blocks, id_properties_ui, custom properties, type mapping, 5.0 storage separation | idprop |
bpy.ops, calling operators, return values, execution_context, poll, operator search | bpy-ops |
bpy.app, version info, paths, cachedir, is_job_running, handlers list, build info | bpy-app |
bpy.utils, class registration, previews, script paths, expose_bundled_modules, VFX library access | bpy-utils |
bpy.msgbus, subscribe_rna, publish_rna, message bus subscriptions, path_resolve for keys | bpy-msgbus |
Operators & UI
| Query is about... | Read |
|---|---|
Writing custom operators, bl_idname, bl_options, execute/invoke/check, operator properties, menu/keymap registration | operators-custom |
Modal operators, modal() method, event types/values, mouse coords, timers, draw callbacks, header_text_set | operators-modal |
Panels, bl_space_type/bl_region_type/bl_category, sub-panels, draw/poll, UILayout basics (row, column, box, split, prop, operator) | panels-ui |
Advanced UI: prop_search, template_ID, template_list, UIList subclass, filter_items, icon previews, dynamic enums, popover, menu_pie | ui-layout-advanced |
Gizmos, GizmoGroup, built-in gizmo types (arrow, dial, move, cage, primitive), target_set_prop/handler, matrix_basis | gizmos |
Addon / Extension Development
| Query is about... | Read |
|---|---|
Addon structure, bl_info, register/unregister, multi-file addons, importlib.reload, class registration order | addon-structure |
Extensions system, blender_manifest.toml schema, local/remote repos, CLI build/install, permissions, publishing | extensions-system |
Addon preferences, AddonPreferences, bl_idname = __package__, accessing prefs, bl_system_properties_get, keymap registration | addon-preferences |
| Porting from 4.x to 5.0/5.1, breaking changes, before/after code, migration patterns | porting-from-4x |
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 |
Mesh advanced: calc_smooth_groups, validate, calc_normals_split, from_pydata, calc_loop_triangles, domain_size | mesh-advanced |
BMesh: bmesh.new, from_edit_mesh/from_mesh/to_mesh/free, verts/edges/faces/loops, layers, ensure_lookup_table, bmesh.ops | bmesh |
Curves data: Curves type, curve types (POLY/BEZIER/NURBS/CATMULLROM), `resizecurves/removecurves`/`settypes`, point attributes | curves-data |
Geometry Nodes API: modifier socket access, output attributes, GeometrySet, baking, viewer node, node tool idname | geometry-nodes-api |
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 |
Compositor nodes: compositing_node_group, CompositorNode→ShaderNode rename table, GroupOutput replaces Composite, file_output_items | compositor-nodes |
Materials API: creating materials, use_nodes, Principled BSDF inputs, image textures, material slots, World material | materials-api |
Node tree interface: new_socket, new_panel, socket_type enum, items_tree, Group Input/Output nodes | node-tree-interface |
Node closures and bundles: Combine/Separate Bundle, repeat zones, inline_shader_nodes API for render engines | node-closures-bundles |
Animation
| Query is about... | Read |
|---|---|
Actions (slotted system): action.slots, ActionSlot, layers, strips, channelbags, fcurves.new/ensure, fcurve_ensure_for_datablock | animation-actions |
Keyframes, FCurves, drivers: keyframe_insert/delete, keyframe_points, handle types, FCurve modifiers, driver expressions, variables | keyframes-drivers |
NLA: nla_tracks, strips, blend types, extrapolation, influence, push_down, baking | nla |
Handlers and timers: frame_change_pre/post, depsgraph_update, load_pre/post, @persistent, bpy.app.timers | handlers-timers |
Rendering & GPU
| Query is about... | Read |
|---|---|
Render API: RenderEngine subclass, render/viewupdate/viewdraw, RenderResult/Layer/Pass, engine ID renames, pass name renames | render-api |
GPU module: gpu.shader.from_builtin, create_from_info, GPUShader/GPUTexture/GPUBatch/GPUVertBuf, gpu.state, gpu.matrix, POLYLINE/POINT variants | gpu-module |
GPU extras: batch_for_shader, draw_texture_2d, draw_circle_2d, batch creation workflow | gpu-extras |
GPU offscreen: GPUOffScreen creation, bind/unbind, draw_view3d, depth format deprecations, render-to-texture | gpu-offscreen |
GPU drawing: draw_handler_add, handler removal, 3D/2D drawing workflows, color space handling | gpu-drawing |
Text drawing: blf module, font loading, size/position/draw/color, shadow, rotation, clipping, word wrap, bind_imbuf | blf |
Math & Utilities
| Query is about... | Read |
|---|---|
mathutils: Vector, Matrix, Quaternion, Euler, Color, arithmetic, freeze(), buffer protocol (float32) | mathutils |
mathutils.geometry: intersect_*, barycentric_transform, tessellate_polygon, convex_hull_2d, distance_point_to_plane | mathutils-geometry |
KDTree, BVHTree, noise: spatial queries, find/find_n/find_range, ray_cast, find_nearest, overlap, noise functions | mathutils-spatial |
bl_math: clamp, lerp, smoothstep, pingpong, round_to_even | bl-math |
bpy.path: abspath (// resolution), relpath, clean_name, ensure_ext, native_pathsep | bpy-path |
bpy_extras: view3d_utils, io_utils (ImportHelper/ExportHelper), mesh_utils, object_utils, anim_utils | bpy-extras |
Scene & Objects
| Query is about... | Read |
|---|---|
Object transforms: matrix_world/local/basis/parent_inverse, decompose, delta transforms, constraints, parenting, to_mesh | objects-transforms |
Collections, scene management: Collection hierarchy, objects.link/unlink, all_objects, layer_collection, scene.ray_cast, cursor | collections-scene |
Dependency graph: evaluated_depsgraph_get, id_eval_get, object_instances, DepsgraphObjectInstance, updates, original vs evaluated | depsgraph |
| Armatures: bones, edit_bones, PoseBone, BoneCollection API, select properties, Geometry Attribute constraint, mode switching | armatures |
I/O & Pipeline
| Query is about... | Read |
|---|---|
| Import/export operators: glTF, FBX, OBJ, STL, Alembic — key parameters, batch export, format selection | import-export |
USD pipeline: USD import/export, Python export hooks, pxr module access, stage traversal | usd-pipeline |
File I/O: bpy.ops.wm.open_mainfile/save_mainfile, library overrides, asset system, bpy.data.libraries, forward compatibility | file-io |
Image & Audio
| Query is about... | Read |
|---|---|
imbuf module: ImBuf creation, pixel access, load/save, format conversion, gpu.texture.from_image() | imbuf |
aud module: Device, Sound, Handle, playback, filters, sequencing | aud |
Grease Pencil & Annotations
| Query is about... | Read |
|---|---|
Grease Pencil v3: layers, frames, drawings, add_strokes, attribute-based point access, stroke materials | grease-pencil |
| Annotations: annotation layers/frames/strokes, rename table from legacy GP types | annotations |
Freestyle
| Query is about... | Read |
|---|---|
| Freestyle types: type hierarchy, Nature constants, iterators, Interface0D/1D, ViewEdge, StrokeVertex | freestyle-types |
| Freestyle scripting: pipeline (Selection→Chaining→Splitting→Sorting→Creation), predicates, shaders, style modules | freestyle-scripting |
Video Sequence Editor
| Query is about... | Read |
|---|---|
VSE strips: strip types, sequences.new_* methods, strip properties, channels, transform, proxy | sequencer-strips |
| VSE effects and retiming: effect strips, speed control, retiming keys, time property renames | sequencer-effects-retiming |
Scripting Environment
| Query is about... | Read |
|---|---|
Text editor scripting: Text data-block API, console operators, script templates, CLI flags, --python, --python-expr | text-editor-scripting |
Multi-File Loading Rules
Load the minimum files needed to answer the query accurately:
- 1 file — Simple, single-topic queries (e.g., "how do I add a keyframe" →
keyframes-drivers.md)
- 2–3 files — Cross-topic queries (e.g., "build an addon with a modal operator" →
addon-structure.md + operators-modal.md)
- Maximum 5 files — Complex queries spanning multiple systems (e.g., "GPU-accelerated
viewport overlay addon with custom gizmos" → addon-structure.md + operators-modal.md + gpu-module.md + gpu-drawing.md + gizmos.md)
Common multi-file combinations:
- Addon with UI panel:
addon-structure.md+panels-ui.md - Addon with custom properties:
addon-structure.md+bpy-props.md - Mesh processing script:
mesh-data.md+bmesh.md - Material setup script:
materials-api.md+shader-nodes.md - Animation script:
animation-actions.md+keyframes-drivers.md - Geometry Nodes modifier setup:
geometry-nodes-api.md+bpy-props.md - Render engine addon:
render-api.md+gpu-module.md+gpu-drawing.md
When a reference file cross-references another file with See [topic](file.md), load that file only if the user's query directly involves that topic. Do not preemptively load all cross-referenced files.
For porting questions, always load porting-from-4x.md plus the specific topic file(s) involved.
If uncertain which file covers a topic, consult this routing table first — every Blender Python API topic maps to exactly one primary file.
Code Conventions
Imports. Always import bpy explicitly. For standalone modules, import directly:
import bpy
import bmesh
from mathutils import Vector, Matrix, Quaternion, Euler
import gpu
from gpu_extras.batch import batch_for_shader
import blfDo not use from bpy import *. Do not import private bundled modules directly — access VFX platform libraries through bpy.utils.expose_bundled_modules().
Naming. Follow Blender conventions: UPPER_CASE for operator bl_idname category, snake_case for operator name suffix, CamelCase for class names. Operator idnames use dot notation: "object.my_operator". Class names include a standardized prefix:
CATEGORY_OT_namefor operators (e.g.,OBJECT_OT_my_operator)CATEGORY_PT_namefor panels (e.g.,VIEW3D_PT_my_panel)CATEGORY_MT_namefor menus (e.g.,VIEW3D_MT_my_menu)CATEGORY_UL_namefor UI lists (e.g.,OBJECT_UL_my_list)CATEGORY_HT_namefor headers
Error handling. Check poll() before calling operators, or wrap in try/except for RuntimeError. Never silently swallow exceptions from Blender API calls. Use self.report({'ERROR'}, msg) inside operators to surface errors to users. Check return values from operators — they return a set: {'FINISHED'}, {'CANCELLED'}, or {'RUNNING_MODAL'}.
Type annotations. Use type annotations for operator properties via bpy.props, not Python type hints. PropertyGroup fields must use bpy.props descriptors — plain Python attributes are ignored by RNA. Correct pattern:
class MySettings(bpy.types.PropertyGroup):
scale: bpy.props.FloatProperty(name="Scale", default=1.0) # correct
# scale = 1.0 # WRONG — ignored by RNAContext managers. Use context.temp_override() for operator context:
with context.temp_override(active_object=obj, selected_objects=[obj]):
bpy.ops.object.duplicate()Use bmesh.new() with explicit free() calls (BMesh is not a context manager). Use offscreen.bind() / offscreen.unbind() for GPU offscreen rendering.
Performance: foreach_get/set. For bulk data access (mesh vertices, pixels, attributes), always prefer foreach_get/foreach_set over Python loops. These methods operate on flat arrays and are orders of magnitude faster:
import numpy as np
coords = np.empty(len(mesh.vertices) * 3, dtype=np.float32)
mesh.vertices.foreach_get("co", coords)
coords = coords.reshape(-1, 3)Use matching numpy dtypes for best performance (np.float32 for coordinates, np.int32 for indices, np.bool_ for selections). The sequence must be uni-dimensional — multi-component attributes like 3D vectors are flattened to [x0, y0, z0, x1, y1, z1, ...].
Avoid stale references. Never store bpy.types.ID references (Object, Mesh, etc.) across undo, file load, or operations that may re-allocate data. Re-query from bpy.data by name:
# WRONG — obj may become stale after undo
obj = bpy.data.objects["Cube"]
# ... undo happens ...
obj.location # crash or undefined behavior
# CORRECT — re-query when needed
name = "Cube"
obj = bpy.data.objects.get(name)
if obj is not None:
obj.location = (1, 2, 3)Operator vs data API. Prefer the data API (bpy.data, direct attribute access) over operators when you need predictable, context-independent behavior. Operators are designed for interactive use and require specific context. For example, prefer mesh.vertices.add(n) over bpy.ops.mesh.primitive_cube_add() when building geometry programmatically.
Registration order. Register PropertyGroups before classes that reference them. Unregister in reverse order. A typical pattern:
classes = (MyPropertyGroup, MY_OT_operator, MY_PT_panel)
def register():
for cls in classes:
bpy.utils.register_class(cls)
bpy.types.Scene.my_settings = bpy.props.PointerProperty(type=MyPropertyGroup)
def unregister():
del bpy.types.Scene.my_settings
for cls in reversed(classes):
bpy.utils.unregister_class(cls)Depsgraph updates. After modifying data programmatically, call depsgraph.update() or view_layer.update() if you need the evaluation to reflect your changes immediately. Without this, the viewport may not refresh until the next redraw cycle.
Mode awareness. Many operations require a specific mode. Check context.mode before operating. Mesh editing requires EDIT_MESH mode for bmesh fromeditmesh, while OBJECT mode is needed for most bpy.ops.object.* operators. Use bpy.ops.object.mode_set(mode='EDIT') to switch modes when necessary.
5.1 Convention
Items specific to Blender 5.1 appear as blockquote callouts at the relevant location in each reference file:
5.1: Example callout — bpy.app.cachedir returns the platform cache directory.The 5.1 label indicates the feature requires Blender 5.1 or later. These are not tagged as beta or experimental — 5.1 is treated as a stable target alongside 5.0.