Blender Python API: What is a Custom Operator?

A custom operator in the Blender Python API is a user-defined class that encapsulates specific tools, actions, or automated tasks within Blender's architecture. This article explains what custom operators are, breaks down their core components and execution lifecycle, and demonstrates how they integrate into Blender's user interface, shortcut systems, and scripting workflows.

In Blender, almost every user action—from adding a mesh to rendering an image—is executed through an operator. The Blender Python (bpy) API allows developers to create custom operators by subclassing bpy.types.Operator. Once registered, a custom operator behaves identically to Blender’s native internal tools.

Core Structure of a Custom Operator

A custom operator requires specific class attributes and methods to function properly:

  • bl_idname: A unique identifier string written in lowercase using a dot notation format (e.g., "object.custom_tool"). The first part represents the module or category, and the second represents the action name. Python scripts call the operator using this identifier via bpy.ops.object.custom_tool().
  • bl_label: A human-readable name that appears in the interface, tooltips, and the operator search menu (F3).
  • bl_options: Optional flags (such as {'REGISTER', 'UNDO'}) that define operator behavior, such as enabling undo history or showing settings in the operator redo panel.

Key Lifecycle Methods

Custom operators rely on predefined methods to handle execution and context validation:

  • execute(self, context): The mandatory entry point for non-interactive operators. It executes the core algorithm and must return a set containing status strings, typically {'FINISHED'} upon successful completion or {'CANCELLED'} if an error occurs.
  • poll(cls, context): An optional class method that verifies whether the execution environment is valid before running. If poll returns False, the operator cannot be triggered, and its corresponding UI button will appear grayed out. For example, it can restrict execution to when an active mesh object is selected in Edit Mode.
  • invoke(self, context, event): Used for interactive operations or when a dialog box is required before execution. It captures user input, mouse coordinates, and window events.

Registration and Accessibility

For Blender to recognize a custom operator, it must be registered with the application runtime using bpy.utils.register_class(). Once registered, the operator becomes globally accessible throughout Blender:

  1. Python Console and Scripts: Callable directly through the bpy.ops module.
  2. User Interface: Attachable to panels, menus, headers, and pie menus within bpy.types.Panel or bpy.types.Menu definitions.
  3. Keymaps: Bindable to custom keyboard shortcuts and mouse actions in the Blender Preferences.
  4. Operator Search: Searchable directly by its bl_label in the operator search dialog.