How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/tmhsdigital/blender-developer-tools --skill drivers-and-app-handlersBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Drivers and Application Handlers
Trigger
Use this skill when the user:
- Wants property A to follow property B with some math (driver)
- Asks about
driver_add,FCurve.driver,driver.expression,driver_namespace - Wants to run code on file save, file load, frame change, depsgraph update, or process exit
- Mentions
bpy.app.handlers,save_pre,load_post,depsgraph_update_post,exit_pre - Has a driver expression that fails security checks because it tries to call a Python function
This skill bundles two related "reactive" patterns. They show up together often (a driver that calls a function registered on a handler), so they share one skill.
Part 1: Drivers
What a driver is
A driver replaces a static animation curve with a real-time-evaluated expression. It is attached to one property (the target) and reads zero or more other properties (the variables), then evaluates a string expression to compute the target's value on each frame.
Concretely: an FCurve whose .driver field is set is a driver. The animation system evaluates driver.expression instead of sampling the curve.
The Driver API
import bpy
def add_simple_driver(obj, data_path, index, expression):
"""Attach a driver to obj.data_path[index] that evaluates `expression`.
Returns the FCurve so the caller can add variables.
"""
fcurve = obj.driver_add(data_path, index)
fcurve.driver.type = 'SCRIPTED'
fcurve.driver.expression = expression
return fcurvedriver_add(data_path, index):
data_pathis the RNA path of the property, like"location"or"scale". A user custom (ID) property set withobj["my_custom_prop"] = 1.0is'["my_custom_prop"]'; a registeredbpy.propsproperty is its plain name,"my_prop". On 5.0+'["my_prop"]'no longer resolves a registered property (ValueError), though it did on 4.x.indexis the array index for vector or color properties (0 = X, 1 = Y, 2 = Z), or-1for scalar properties.- Returns the
FCurvewhose.driveris now active.
Adding variables to a driver
Drivers reference other properties by adding variables to their driver.variables collection. Each variable has a name (used in the expression) and one or two property targets.
fcurve = obj.driver_add("location", 0)
fcurve.driver.type = 'SCRIPTED'
var = fcurve.driver.variables.new()
var.name = 'src_x'
var.type = 'TRANSFORMS'
var.targets[0].id = source_obj
var.targets[0].transform_type = 'LOC_X'
var.targets[0].transform_space = 'WORLD_SPACE'
fcurve.driver.expression = 'src_x * 2.0'Common variable types:
'SINGLE_PROP': read any RNA property. Settargets[0].id = some_idandtargets[0].data_path = 'some.path'. The target id pointer defaults to theOBJECTtype; to point at a non-object datablock (a Scene, Material, etc.) settargets[0].id_typefirst, e.g.targets[0].id_type = 'SCENE', otherwise theid =assignment raisesTypeError.'TRANSFORMS': read a transform channel. Settransform_type(LOC_X,ROT_Y,SCALE_Z, etc.).'ROTATION_DIFF': angle between two bones in radians.'LOC_DIFF': distance between two object locations.
The expression security model
Driver expressions run on every depsgraph evaluation. A SCRIPTED expression is one of two kinds, and they are trusted differently:
- Simple expressions always run. Blender evaluates the documented simple subset (arithmetic, comparisons, driver variables,
frame, and whitelisted math such assin,cos,sqrt,pi,radians,min,max) without Python, so they run even with script auto-execution off. - Everything else needs Python auto-execution. That includes every call to a `bpy.app.driver_namespace` function and any attribute access such as
bpy.context.scene.frame_current. Blender ships with auto-execution off (preferences.filepaths.use_scripts_auto_executeisFalseon a factory 4.5.11 and 5.2.1). A user who opens your.blendin a normal GUI session gets dead drivers unless they open it as Trusted Source, enable Preferences > Save & Load > Auto Run Python Scripts, or launch with--enable-autoexec/-y. See the manual's Drivers > Troubleshooting: a scripted expression outside the simple subset needs Trusted Source or Auto Run Python Scripts.
driver_namespace does not make a function safe or trusted. It only makes the name resolvable once Python is allowed to run. The gate is auto-execution.
Check which kind you wrote with driver.is_simple_expression. Measured on 4.5.11 and 5.2.1:
| Expression | is_simple_expression |
|---|---|
1.4 + sin(3 * 0.6), frame / 10, max(1, 2), 1.0 | True |
wave_scale(0) (a driver_namespace function) | False |
bpy.context.scene.frame_current | False |
Prefer simple expressions and driver variables when the `.blend` will be shared. Read data through variables (SINGLE_PROP, TRANSFORMS) and keep the expression in the simple subset. Reach for a namespace function only when the add-on that registers it will be installed wherever the file is opened, and tell the user the file needs Auto Run.
Headless tests cannot see this failure. --background runs still evaluated a reopened file's namespace driver (so a save-and-reopen check passes). Assert is_simple_expression instead of trusting a background evaluation.
The driver_namespace escape hatch
When a driver needs custom Python logic, register the function in bpy.app.driver_namespace:
import bpy
import math
def smooth_step(t):
"""Smoothstep easing: 3t^2 - 2t^3 on [0, 1]."""
t = max(0.0, min(1.0, t))
return t * t * (3.0 - 2.0 * t)
bpy.app.driver_namespace['smooth_step'] = smooth_step
fcurve = obj.driver_add("location", 2)
fcurve.driver.type = 'SCRIPTED'
var = fcurve.driver.variables.new()
var.name = 't'
var.type = 'SINGLE_PROP'
var.targets[0].id_type = 'SCENE' # required before assigning a non-Object id
var.targets[0].id = bpy.context.scene
var.targets[0].data_path = 'frame_current'
fcurve.driver.expression = 'smooth_step((t - 1.0) / 100.0) * 5.0'The function name in driver_namespace must match the call in the expression.
driver_namespace is reset on every file load. Registering only in register() works until the user opens a file: the drivers then evaluate with the function missing, raise NameError: name 'smooth_step' is not defined, and are disabled (driver.is_valid = False). They stay disabled even after the function is added back. Re-register from a @persistent load_post handler and re-enable the drivers there:
import bpy
from bpy.app.handlers import persistent
@persistent
def restore_driver_functions(_filepath=None):
bpy.app.driver_namespace['smooth_step'] = smooth_step
# Drivers that failed during load stay off until re-enabled.
for ids in (bpy.data.objects, bpy.data.shape_keys, bpy.data.materials):
for id_data in ids:
anim = id_data.animation_data
for fcurve in (anim.drivers if anim else ()):
fcurve.driver.is_valid = True
def register():
bpy.app.driver_namespace['smooth_step'] = smooth_step
bpy.app.handlers.load_post.append(restore_driver_functions)
def unregister():
if restore_driver_functions in bpy.app.handlers.load_post:
bpy.app.handlers.load_post.remove(restore_driver_functions)
bpy.app.driver_namespace.pop('smooth_step', None)Extend the ID collections to wherever your add-on puts drivers (node groups, scenes, cameras). Measured on 4.5.11 and 5.2.1: without the handler, a saved and reopened file leaves the driver dead; with it, the driver evaluates again.
Removing drivers
obj.driver_remove("location", 0)
obj.driver_remove("location", -1)The first form removes the driver on a specific channel. The second (with -1) removes drivers on all channels of a vector property.
Part 2: Application Handlers
What a handler is
A handler is a Python callable registered against a Blender event. When the event fires, every callable in the handler's list is called with a documented signature. Handlers run in registration order and exceptions in one do not stop the others (Blender catches and logs).
The handlers live as lists at bpy.app.handlers.<event>. To register, append; to unregister, remove.
Common handlers and their signatures
| Handler | Signature | Fires when |
|---|---|---|
save_pre | (filepath: str) | Before the .blend is written. The argument is the file being saved (empty string for the startup file), not a Scene. Use to clean up data you don't want serialized. |
save_post | (filepath: str) | After the .blend is written. Same single filepath argument. |
load_pre | (filepath: str) | Before a .blend is loaded. The argument is the file being loaded. |
load_post | (filepath: str) | After a .blend is loaded. Use to validate or migrate add-on data. |
depsgraph_update_pre | (scene, None) | Before a depsgraph evaluation pass. The second argument is None, not a Depsgraph. |
depsgraph_update_post | (scene, depsgraph) | After a depsgraph evaluation pass. Fires very frequently; must be O(1) or near-O(1). |
frame_change_pre | (scene, None) | Before frame is set. The second argument is None; the depsgraph is not available yet. |
frame_change_post | (scene, depsgraph) | After frame is set. |
exit_pre (new in 5.1) | (interactive: bool) | Before Blender shuts down. Use for resource cleanup, telemetry flush, etc. The argument is True for an interactive (GUI) exit and False in --background. A handler written as (*args) receives (bool, None). |
The save/load handlers (save_pre, save_post, load_pre, load_post) all receive the file path as a string as their single argument, not a Scene. (Verified empirically on 4.5.10 LTS and 5.1.1. The `bpy.app.handlers` docs type these as Callable[[str], None]; save_pre is described as "on saving a blend file (before). Accepts one argument: the file being saved, an empty string for the startup-file." — the load handlers use the same wording with "the file being loaded".) Only the _post depsgraph/frame-change handlers receive (scene, depsgraph). The _pre ones get (scene, None), so a handler that calls depsgraph.<anything> there raises AttributeError: 'NoneType' object has no attribute .... Measured on 4.5.11 and 5.2.1: frame_change_pre and depsgraph_update_pre get ['Scene', 'NoneType'], the _post variants ['Scene', 'Depsgraph']. If a pre handler truly needs evaluated data, call bpy.context.evaluated_depsgraph_get(), and not from inside a depsgraph handler, where it can trigger the evaluation the handler is part of. Usually the right fix is to move the work to the _post handler.
exit_pre was measured on 5.2.1: a --background exit passes False, a windowed wm.quit_blender() passes True.
The exit_pre handler in 5.1 is particularly useful for add-ons that need to release external resources (sockets, log files, child processes) deterministically before the process terminates.
The canonical handler pattern
import bpy
from bpy.app.handlers import persistent
@persistent
def on_save_pre(filepath):
"""Clear temporary cache data before save so it doesn't bloat the .blend.
The handler argument is the path being saved (a string), not a Scene, so
reach the scene(s) through bpy.data.
"""
for scene in bpy.data.scenes:
if 'my_addon_cache' in scene:
del scene['my_addon_cache']
def register():
bpy.app.handlers.save_pre.append(on_save_pre)
def unregister():
if on_save_pre in bpy.app.handlers.save_pre:
bpy.app.handlers.save_pre.remove(on_save_pre)The @persistent decorator
By default, handlers are removed when a new .blend loads (so each file gets a clean handler list). Decorate with @persistent to keep your handler attached across file loads. This is what add-ons almost always want.
Performance contract
Handlers run on the main thread, synchronously, on every event. The user feels every millisecond. Rules:
- Make handlers fast or asynchronous. A 10ms handler on
depsgraph_update_postslows playback noticeably. - Guard against recursion. A
depsgraph_update_postthat modifies the scene re-triggers the handler. Use a module-level flag orbpy.app.handlers.depsgraph_update_postremoval to break loops. - Defend against missing data. Handlers run before your add-on may have fully initialized (load_post fires while UI is still rebuilding). Check membership before dereferencing.
- Always pair register/unregister. Forgetting to remove a handler on add-on disable leaves a zombie callback that fires forever.
Worked example: track save count per file
import bpy
from bpy.app.handlers import persistent
@persistent
def increment_save_count(filepath):
# save_pre runs before the write, so the new count lands in the file being
# saved (a save_post write would only reach the next save). It receives the
# target path. ID-property keys are limited to 63 characters, so key by the
# file name, never the full path, which raises KeyError when longer.
scene = bpy.context.scene
key = bpy.path.basename(filepath)[:63] or "untitled"
counts = scene.get('save_counts', {})
counts[key] = counts.get(key, 0) + 1
scene['save_counts'] = counts
def register():
bpy.app.handlers.save_pre.append(increment_save_count)
def unregister():
if increment_save_count in bpy.app.handlers.save_pre:
bpy.app.handlers.save_pre.remove(increment_save_count)Worked example: cleanup on exit (5.1+)
import bpy
from bpy.app.handlers import persistent
@persistent
def cleanup_on_exit(*args):
"""Release the external log file handle before the process terminates.
exit_pre's argument is unused here; accept *args to stay signature-proof.
"""
global _log_handle
if _log_handle is not None:
_log_handle.close()
_log_handle = None
def register():
bpy.app.handlers.exit_pre.append(cleanup_on_exit)
def unregister():
if cleanup_on_exit in bpy.app.handlers.exit_pre:
bpy.app.handlers.exit_pre.remove(cleanup_on_exit)The exit_pre handler list is new in Blender 5.1. On 4.5 LTS, fall back to OS-level atexit registration, which fires later and has fewer guarantees about access to bpy state.
Common AI mistakes
- Calling Python functions in a driver expression without registering them. Hits the security block. Either rewrite as math, or register via
bpy.app.driver_namespace. - Registering a driver function only in `register()`.
driver_namespaceis reset on file load, so the driver dies withNameErroron the first file the user opens and stays disabled. Re-register and resetdriver.is_validfrom a@persistentload_posthandler. - Forgetting `@persistent` on handlers. The handler vanishes on the next file load and the user thinks the add-on broke.
- Doing real work inside `depsgraph_update_post`. This handler fires on every depsgraph evaluation, which is many times per second during playback or interaction. Anything more than O(1) bookkeeping causes user-visible slowdown.
- Recursively modifying the scene from a depsgraph handler. The modification triggers another depsgraph evaluation, which calls the handler, which modifies the scene. Infinite loop, often manifesting as a hang.
- Asymmetric register/unregister. The handler is appended on register but not removed on unregister. Disabling the add-on leaves the callback in place. After enable/disable cycles, the callback runs N times per event.
- Treating the `save_pre` argument as a Scene. The save/load handlers receive the file path string (empty for the startup file), not a Scene. Name the parameter
filepath(or take*args), and reach scenes viabpy.context.scene/bpy.data.scenes. A membership test like'key' in arg0against the path string is silently wrong, anddel arg0['key']raisesTypeError. - Doing exit cleanup in the script body instead of `exit_pre`. A
--background --pythonscript cansys.exit(0)without the handler firing if you never registered it. The witness is a sidecar written fromexit_pre, asserted after the process dies.
Version correctness
| Topic | 4.5 LTS | 5.1 / 5.2 LTS |
|---|---|---|
exit_pre handler | Not available | New in 5.1; use atexit fallback for 4.x |
save_pre / save_post signature | (filepath) — a string | (filepath) — a string (unchanged) |
driver_namespace | Available; reset on file load | Same (re-register from load_post) |
| Driver security | Already restrictive | Same |
See also
- Snippet
driver-with-custom-function.pyfor the driver_namespace pattern. - Snippet
app-handler-registration.pyfor save_pre with proper unregister. - Example
exit-pre-sidecarforexit_prewriting a post-exit sidecar (5.1+; skip 4.5). - Skill
custom-propertiesfor the data the driver might be reading.
<!-- examples:begin (generated by scripts/buildexamplesindex.py from examples/skills.json; do not edit) -->
Runnable examples
Each example runs headless, asserts the contract, and exits non-zero when it breaks. Run one with blender --background --python <script> --; pass a falsifier flag to watch the check fail.
- `driver-wave`: A driver_namespace function driving sixteen organ-pipe heights through SCRIPTED drivers — the sine skyline of the pipe tops is entirely driver-evaluated. Falsify:
--flat-expr(exit 3). - `exit-pre-sidecar`:
bpy.app.handlers.exit_prewrites$BDT_SMOKE_SIDECARas Blender dies. Blender 5.1+. Falsify:--atexit-instead(harness fails the sidecar).
Snippets
Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.
<!-- examples:end -->
References
bpy.app.handlers: https://docs.blender.org/api/current/bpy.app.handlers.htmlbpy.types.Driver: https://docs.blender.org/api/current/bpy.types.Driver.htmlbpy.types.FCurve.driver: https://docs.blender.org/api/current/bpy.types.FCurve.htmlbpy.app.driver_namespace: https://docs.blender.org/api/current/bpy.app.html- Blender 5.1 release notes: https://developer.blender.org/docs/release_notes/5.1/