Latest news
Unreal Engine Lumen Settings: A Guide to Lighting and Reflections in Architectural InteriorsIntel Nova Lake-S spotted in tests with 28 cores and 5.2 GHzCreating Architectural Videos with Veo 3.1: From Prompt to ScenePreparing Lightmap UVs from Blender to Unreal Engine: A Step-by-Step GuideCADQuader beta launches: converts STEP and IGES files to quad meshesPreparing Architectural Sheets in Rhino 8: Layout, Detail and PDF GuideArchitectural Image Creation with Images 2.6: From Prompt to Controlled RevisionsThéâtre Royal de Rabat completed: A design inspired by the Bouregreg riverbankTransfer a USD Scene from Blender to Unreal Engine: Step-by-Step GuideInkling 2 Mini released: Recursive architecture focuses on local use
TutorialsBlenderOMAMari

Getting started with the Blender Python API: First automations for architectural scenes

Blender’s Python API lets you inspect scene data, add custom properties to objects, and create simple tools. This beginner’s guide walks through the first automation steps for architectural visualization scenes.

A design studio desk with an architectural interior modelAI image
Representative image, generated with AI.Image: 3dsınıfı / FCA AI

In brief

  1. The Python Console can be used to try short commands and explore the API with autocomplete.
  2. bpy.data provides access to object, scene, and material data in the open Blender file.
  3. Custom properties can be added to objects and saved with the blend file.
  4. An operator can be registered in Blender and run from the search menu.

What will you learn in this guide?

The Blender Python API lets you access and edit much of the data that can be changed in the interface using Python. For architectural modeling and visualization, this can mean inspecting scene elements, adding project information to objects, or turning repetitive tasks into a tool. In this guide, you’ll first read scene data, then add a custom property to the active object, and finally create a simple operator.

The examples here are based on the methods in Blender’s official quickstart documentation for the Python API. The API is described as generally stable, although some parts of the documentation are still being developed. For that reason, it’s good practice to try a feature in a small test scene before using it in production files.

Requirements

  • Blender must be installed. The source documentation does not specify a particular Blender version number, so we do not give a definitive version compatibility number here.

  • You do not need to install Python separately; the examples run in Blender’s Python Console or Text Editor.

  • The sources do not specify any account or paid license requirements.

  • Enabling Developer Extras and Python Tooltips in Blender’s preferences is useful when exploring the API. Button tooltips can help you find related Python attributes and operator names.

The Python Console is useful for short commands and experiments. For editing and saving scripts with multiple lines, Blender’s Scripting workspace and Text Editor are more convenient. You can access this workspace from the tabs in the top bar.

Step by step: access scene data and create your first tool

1. List scene objects with Python

Open the Scripting workspace and switch to the Python Console. The console also comes in handy when exploring data and property names in bpy, thanks to its autocomplete feature. Run this code to print the objects in the current scene one by one:

python
import bpy

for ob in bpy.context.scene.objects:
    print(ob)

This example iterates through the current scene’s object collection and sends each object to the console output. In an architectural file, this is a basic starting point for quickly checking which objects are in the scene. You can later add operations inside the loop to inspect names, data, or other attributes using the access methods documented in the source.

2. Find data through bpy.data

Data blocks in a Blender file are accessed through bpy.data. The documentation gives examples of collections such as objects, scenes, and materials. You can access a collection item by name:

python
bpy.data.objects["Cube"]

You can also access the same collection by numerical index, but the documentation warns that an item’s index can change while the script is running. So when looking for a specific scene element, accessing it by name is clearer than treating its index as fixed. Bear in mind that the name in your file may be different; Cube in this example is simply the sample object name used in the documentation.

3. Add custom information to the active object

You can use the Python API’s custom properties to add information to an object, scene, or collection. The following example stores a text value on the active object, if one exists:

python
import bpy

obj = bpy.context.object
if obj is not None:
    obj["project_note"] = "interior study"

Here, bpy.context.object returns the active object, depending on the context. The condition ensures that nothing happens if there is no active object. According to the source documentation, custom properties of this kind are saved with the blend file and are carried along when objects are duplicated. This makes them useful for adding a project note or simple information defined by your team to an object. Choosing consistent property names makes the data easier to find across multiple scripts and files.

Only basic Python types can be assigned to custom properties: integers, floating-point numbers, strings, arrays of numbers, and dictionaries that meet certain rules. The documentation gives an upper limit of 1024 levels for nested dictionaries; exceeding this depth can cause errors and data loss. This example uses a simple text value, so it does not involve such a nested structure.

4. Turn a repeatable task into an operator

You can define an operator to run a piece of code again from within Blender. The following example creates a simple operator that prints the scene’s objects and prevents execution if there is no active object:

python
import bpy

def main(context):
    for ob in context.scene.objects:
        print(ob)

class SimpleOperator(bpy.types.Operator):
    """Tooltip"""
    bl_idname = "object.simple_operator"
    bl_label = "Simple Object Operator"

    @classmethod
    def poll(cls, context):
        return context.active_object is not None

    def execute(self, context):
        main(context)
        return {'FINISHED'}

def menu_func(self, context):
    self.layout.operator(
        SimpleOperator.bl_idname,
        text=SimpleOperator.bl_label
    )

def register():
    bpy.utils.register_class(SimpleOperator)
    bpy.types.VIEW3D_MT_object.append(menu_func)

def unregister():
    bpy.utils.unregister_class(SimpleOperator)
    bpy.types.VIEW3D_MT_object.remove(menu_func)

if __name__ == "__main__":
    register()

In the Scripting workspace, select the Text Editor, click New to create a new text data block, paste the code, and click Run Script. In the source documentation’s example, after registering the operator, you can search for Simple using Operator Search. The poll() check prevents the operator from running when there is no active object. This matters when a script depends on the user context.

5. Keep the console and interface context in mind

The contents of bpy.context can vary depending on the area where the code is run. The Python Console and 3D Viewport may not have the same context members. Context values also cannot be changed directly; the source explains that directly assigning the active object results in an error, and that bpy.context.view_layer.objects.active can be used instead. If an operator behaves unexpectedly, first check which area and mode it is running in.

Common mistakes

  • Using an index as a permanent identifier: Collection indices can change while the script is running. Accessing an item by name is clearer; make sure that name actually exists in the file.

  • Assuming every operator will work everywhere: Some operators require the right area, mode, or selection. The poll() condition checks whether these requirements are met; calling an operator with an invalid context can produce an error.

  • Trying to change context directly: bpy.context is described as read-only. If you need to make a change, use the documented data API or an appropriate API function.

  • Packing complex data into custom properties: Supported types are limited, and dictionary values must also consist of basic types. Prefer simple, clear properties.

  • Looking for script output in the wrong place: The example’s print output is sent to the terminal. If you can’t see the result, check Blender’s terminal.

Next steps: architectural and visualization workflows

These basic methods can be a starting point for architects, interior designers, and visualization artists who want to check scene organization or attach extra information to objects. For example, listing the objects in a file can make content checks easier in large scenes, while custom properties can store simple tags defined by a team. On their own, these methods do not provide a specific BIM standard or an automated project management solution; their scope depends on the script and the data used.

Try your first experiments in a copy of a blend file. Then use Python Tooltips and console autocomplete to inspect the data path you need; don’t add an attribute to a production script before verifying what it does. Later, adapt the operator to a real repetitive task and test it with different selections, active objects, and context conditions. For scripts shared within an office, you should also check compatibility with the Blender version; the sources do not provide a specific compatibility matrix.

Source and license

This guide was prepared by adapting examples and explanations from the Blender Python API quickstart documentation. The documentation is licensed under CC BY-SA 4.0. Blender’s 2011 developer blog provides historical context about the expansion of the API documentation; it is not a substitute for current API usage.

Sources

2 sources
C
code.blender.orgcode.blender.org/2011/02/blenderpython-api-docs
Context
D(
docs.blender.org (CC BY-SA 4.0)docs.blender.org/api/current/info_quickstart.html
Summary

Source texts are not republished; short quotes are marked, everything else is our own summary and commentary.

3dsınıfı’s take
3dEditor’s assessment

The Blender Python API can be useful for architecture offices and visualization teams in Turkey, especially for automating small recurring checks and organizing information within files. Because it runs inside Blender, which is available for free, it is practical to get started without additional software costs.

However, the value of automation depends on adapting the script to the team’s file organization and Blender version. It’s important to test first in a copy of the scene, account for parts of the API that are still being developed, and keep custom properties simple. For students, it’s also a tangible way to see how scene data is organized while learning the API.

Frequently asked questions

Where can Blender Python API code be run?

Short commands can be tried in the Python Console. Scripts can be run in the Text Editor in Blender’s Scripting workspace.

How do you add custom information to an object in Blender?

The API supports adding custom properties to objects. These properties can be saved with the blend file and carried along when the object is duplicated.

Does the Blender Python API require a specific version?

The source documentation does not specify a particular version number. The API is described as generally stable, with a note that some parts are still being developed.

Comments and the forum are in Turkish.Join the discussion
+

Related news