Create and Configure Materials with the Blender Python API

What you’ll learn in this guide

Blender’s Python API lets you create materials and configure their basic properties with code, rather than editing them one by one in the interface. In this guide, we’ll create a material data block, name it, and adjust its color, metallic value, and roughness. We’ll then look at the transparency options listed in the API documentation and how to remove an unused material from the database.

The Blender API documentation describes the Material data block as the structure that defines how geometric objects look when rendered. Materials are stored in a collection in Blender’s main database. The examples below follow the documented usage of this collection and its material properties; they don’t cover assigning a material to a specific scene or object type.

Requirements and version note

You’ll need a Blender environment with access to the Blender Python API to use these examples. The source documentation presents its API pages as “current” and doesn’t specify a required Blender version. It’s therefore important to check that the properties listed on the API page are supported by the version used in your project. The sources don’t mention any account, subscription, or separate licensing requirements.

The code snippets are written in Python and use Blender’s bpy API. Run them in an environment with access to Blender’s Python API; the examples don’t guarantee access to Blender data from an external Python environment. Trying them first on a copy of an important project file can help prevent unwanted data changes from affecting the original scene.

Step-by-step material creation

1. Create a new material data block

BlendDataMaterials.new(name) adds a new material to the main database and returns the resulting Material data block. The name parameter is the name assigned to the new data block; according to the documentation, it can’t be None.

import bpy

mat = bpy.data.materials.new(name="Mimari_Materyal")

After this step, the mat variable refers to the material you created. The material is added to the database, but the code doesn’t link it to any specific geometry. For that reason, it’s useful to treat material creation and adding a material to an object’s material collection as separate steps.

2. Set the color and surface properties

The documentation lists diffuse_color, metallic, and roughness among the material properties. diffuse_color is defined as a four-element array. Metallic and roughness values range from 0 to 1; the documented defaults are 0.4 for roughness and 0 for metallic.

mat.diffuse_color = (0.72, 0.64, 0.52, 1.0)
mat.metallic = 0.0
mat.roughness = 0.4

These are example starting values, not a validated recipe for a specific product or real-world building material. You can change the four components of the color array and the numeric properties to suit your needs. When preparing multiple variants, distinctive material names make it easier to manage items in the database.

3. Choose a transparency method

In the current Material API, surface_render_method determines how surfaces are blended and which methods are compatible with certain features. The documentation lists two options: DITHERED and BLENDED. DITHERED handles transparency using a grayscale distribution and is described as compatible with render passes and ray tracing. BLENDED provides colored transparency, but according to the documentation, it can’t be used with render passes or ray tracing.

mat.surface_render_method = 'DITHERED'

This line selects the method used for transparency; it doesn’t set a specific opacity value on its own. If you need colored transparency, you can consider the BLENDED option. When choosing, take into account whether compatibility with render passes or ray tracing is required in your workflow.

alpha_threshold is another documented material property. Pixels with an alpha value above this threshold are rendered. The property ranges from 0 to 1, and the documentation gives 0.5 as its default. If you change this value, test the intended look and check the API description for the Blender version you’re using.

4. Remove the material when needed

If a material is no longer needed, you can remove it from the current blend file with BlendDataMaterials.remove. Setting do_unlink=True removes the links that use the material before deletion. The other parameters relate to updating user counts and ensuring that the interface no longer references the deleted material.

bpy.data.materials.remove(mat, do_unlink=True)

Before running this code, make sure you’ve selected the right material to remove. do_unlink=True also removes its usage links before deletion; this may cause unwanted results if the material still needs to be used in the scene. Trying the deletion step on a copy of the file first is a safe way to check its effects.

Common mistakes

• Assuming an older property is the current method: blend_method is an older property for transparent surfaces, and the documentation recommends using surface_render_method instead. For new work, follow the method in the current API.

• Using use_nodes as a settings toggle: The documentation marks this property as deprecated starting with Blender 5.0. It says setting it has no effect, reading it always returns True, and its removal is planned for Blender 6.0. For that reason, we don’t use it in the example workflow.

• Mixing up color and numeric ranges: diffuse_color is a four-element array, while metallic and roughness take values from 0 to 1. Check the API documentation for the expected data types and ranges.

• Confusing material creation with object assignment: Creating a new data block adds the material to the main database; it doesn’t automatically assign it to a geometry object.

• Overlooking usage links when deleting: do_unlink=True removes all uses of the material before deletion. Don’t run cleanup code in an existing file without understanding the effects of this option.

Use in architecture and visualization workflows

This method is a starting point for architecture firms, interior designers, and visualization teams that want to generate similar material data blocks with code or configure basic properties consistently. Creating materials with code can reduce repetitive manual work when you need to use the same naming and basic value conventions across multiple materials. However, this guide doesn’t describe workflows for assigning materials to objects, behavior in specific render engines, or external material libraries.

Before using this in a project, compare the Blender version you’re using with the current API documentation, and check the transparency method’s compatibility with render passes and ray tracing. The sources don’t specify hardware requirements, performance measurements, fees, or licensing costs, so no firm conclusions can be drawn on those topics. For code shared within an office, it’s a good idea to test data-changing steps such as deletion on a copy of the file first.

Next steps

Once the basic creation and configuration steps are working, consult the Material and BlendDataMaterials API pages for the Blender version you’re using and your project’s needs. The documentation also lists the material data block’s node_tree property and various collections that reference materials; this guide doesn’t explain how to configure them. Basing the next stage of development on documented properties and verified project requirements can help reduce compatibility issues.

Sources and license

This guide is adapted into Turkish from the BlendDataMaterials and Material pages in the Blender API documentation. Both sources are published under the CC BY-SA 4.0 license. The example code was written for this guide; no code has been quoted from the sources.