Utilities (bpy.utils)

This module contains utility functions specific to blender but not associated with blenders internal data.

Submodules

bpy.utils.blend_paths(absolute=False, packed=False, local=False)

Returns a list of paths to external files referenced by the loaded .blend file.

Parameters

absolute (bool) – When true the paths returned are made absolute.
packed (bool) – When true skip file paths for packed data.
local (bool) – When true skip linked library paths.

Returns

path list.

Return type

list[str]

bpy.utils.escape_identifier(string)

Simple string escaping function used for animation paths.

Parameters: string (str) – text
Returns: The escaped string.
Return type: str

bpy.utils.flip_name(name, strip_digits=False)

Flip a name between left/right sides, useful for mirroring bone names.

Parameters

name (str) – Bone name to flip.
strip_digits (bool) – Whether to remove .### suffix.

Returns

The flipped name.

Return type

str

bpy.utils.unescape_identifier(string)

Simple string un-escape function used for animation paths. This performs the reverse of escape_identifier().

Parameters: string (str) – text
Returns: The un-escaped string.
Return type: str

bpy.utils.register_class(cls)

Register a subclass of a Blender type class.

Parameters: cls (type[bpy.types.Panel | bpy.types.UIList | bpy.types.Menu | bpy.types.Header | bpy.types.Operator | bpy.types.KeyingSetInfo | bpy.types.RenderEngine | bpy.types.AssetShelf | bpy.types.FileHandler | bpy.types.PropertyGroup | bpy.types.AddonPreferences | bpy.types.NodeTree | bpy.types.Node | bpy.types.NodeSocket]) – Registerable Blender class type.
Raises: ValueError – if the class is not a subclass of a registerable blender class.

Note

If the class has a register class method it will be called before registration.

bpy.utils.register_cli_command(id, execute)

Register a command, accessible via the (-c / --command) command-line argument.

Parameters

id (str) –
The command identifier (must pass an str.isidentifier check).

If the id is already registered, a warning is printed and the command is inaccessible to prevent accidents invoking the wrong command.
execute (callable) – Callback, taking a single list of strings and returns an int. The arguments are built from all command-line arguments following the command id. The return value should be 0 for success, 1 on failure (specific error codes from the os module can also be used).

Returns

The command handle which can be passed to unregister_cli_command().

This uses Python’s capsule type however the result should be considered an opaque handle only used for unregistering.

Return type

capsule

Custom Commands

Registering commands makes it possible to conveniently expose command line functionality via commands passed to (-c / --command).

import os

import bpy


def sysinfo_print():
    """
    Report basic system information.
    """

    import pprint
    import platform
    import textwrap

    width = 80
    indent = 2

    print("Blender {:s}".format(bpy.app.version_string))
    print("Running on: {:s}-{:s}".format(platform.platform(), platform.machine()))
    print("Processors: {!r}".format(os.cpu_count()))
    print()

    # Dump `bpy.app`.
    for attr in dir(bpy.app):
        if attr.startswith("_"):
            continue
        # Overly verbose.
        if attr in {"handlers", "build_cflags", "build_cxxflags"}:
            continue

        value = getattr(bpy.app, attr)
        if attr.startswith("build_"):
            pass
        elif isinstance(value, tuple):
            pass
        else:
            # Otherwise ignore.
            continue

        if isinstance(value, bytes):
            value = value.decode("utf-8", errors="ignore")

        if isinstance(value, str):
            pass
        elif isinstance(value, tuple) and hasattr(value, "__dir__"):
            value = {
                attr_sub: value_sub
                for attr_sub in dir(value)
                # Exclude built-ins.
                if not attr_sub.startswith(("_", "n_"))
                # Exclude methods.
                if not callable(value_sub := getattr(value, attr_sub))
            }
            value = pprint.pformat(value, indent=0, width=width)
        else:
            value = pprint.pformat(value, indent=0, width=width)

        print("{:s}:\n{:s}\n".format(attr, textwrap.indent(value, " " * indent)))


def sysinfo_command(argv):
    if argv and argv[0] == "--help":
        print("Print system information & exit!")
        return 0

    sysinfo_print()
    return 0


cli_commands = []


def register():
    cli_commands.append(bpy.utils.register_cli_command("sysinfo", sysinfo_command))


def unregister():
    for cmd in cli_commands:
        bpy.utils.unregister_cli_command(cmd)
    cli_commands.clear()


if __name__ == "__main__":
    register()

Using Python Argument Parsing

This example shows how the Python argparse module can be used with a custom command.

Using argparse is generally recommended as it has many useful utilities and generates a --help message for your command.

import os
import sys

import bpy


def argparse_create():
    import argparse

    parser = argparse.ArgumentParser(
        prog=os.path.basename(sys.argv[0]) + " --command keyconfig_export",
        description="Write key-configuration to a file.",
    )

    parser.add_argument(
        "-o", "--output",
        dest="output",
        metavar='OUTPUT',
        type=str,
        help="The path to write the keymap to.",
        required=True,
    )

    parser.add_argument(
        "-a", "--all",
        dest="all",
        action="store_true",
        help="Write all key-maps (not only customized key-maps).",
        required=False,
    )

    return parser


def keyconfig_export(argv):
    parser = argparse_create()
    args = parser.parse_args(argv)

    # Ensure the key configuration is loaded in background mode.
    bpy.utils.keyconfig_init()

    bpy.ops.preferences.keyconfig_export(
        filepath=args.output,
        all=args.all,
    )

    return 0


cli_commands = []


def register():
    cli_commands.append(bpy.utils.register_cli_command("keyconfig_export", keyconfig_export))


def unregister():
    for cmd in cli_commands:
        bpy.utils.unregister_cli_command(cmd)
    cli_commands.clear()


if __name__ == "__main__":
    register()

bpy.utils.unregister_cli_command(handle)

Unregister a CLI command.

Parameters: handle (capsule) – The return value of register_cli_command().

bpy.utils.resource_path(type, major=bpy.app.version[0], minor=bpy.app.version[1])

Return the base path for storing system files.

Parameters

type (str) – string in [‘USER’, ‘LOCAL’, ‘SYSTEM’].
major (int) – major version, defaults to current.
minor (str) – minor version, defaults to current.

Returns

the resource path (not necessarily existing).

Return type

str

bpy.utils.unregister_class(cls)

Unload the Python class from blender.

Parameters: cls (type[bpy.types.Panel | bpy.types.UIList | bpy.types.Menu | bpy.types.Header | bpy.types.Operator | bpy.types.KeyingSetInfo | bpy.types.RenderEngine | bpy.types.AssetShelf | bpy.types.FileHandler | bpy.types.PropertyGroup | bpy.types.AddonPreferences | bpy.types.NodeTree | bpy.types.Node | bpy.types.NodeSocket]) – Blender type class, see bpy.utils.register_class for classes which can be registered.

Note

If the class has an unregister class method it will be called before unregistering.

bpy.utils.keyconfig_init()

bpy.utils.keyconfig_set(filepath, *, report=None)

bpy.utils.load_scripts(*, reload_scripts=False, refresh_scripts=False, extensions=True)

Load scripts and run each modules register function.

Parameters

reload_scripts (bool) – Causes all scripts to have their unregister method called before loading.
refresh_scripts (bool) – only load scripts which are not already loaded as modules.
extensions (bool) – Loads additional scripts (add-ons & app-templates).

bpy.utils.modules_from_path(path, loaded_modules)

Load all modules in a path and return them as a list.

Parameters

path (str) – this path is scanned for scripts and packages.
loaded_modules (set[ModuleType]) – already loaded module names, files matching these names will be ignored.

Returns

all loaded modules.

Return type

list[ModuleType]

bpy.utils.preset_find(name, preset_path, *, display_name=False, ext='.py')

bpy.utils.preset_paths(subdir)

Returns a list of paths for a specific preset.

Parameters: subdir (str) – preset subdirectory (must not be an absolute path).
Returns: Script paths.
Return type: list[str]

bpy.utils.refresh_script_paths(): Run this after creating new script paths to update sys.path

bpy.utils.app_template_paths(*, path=None)

Returns valid application template paths.

Parameters: path (str) – Optional subdir.
Returns: App template paths.
Return type: Iterator[str]

bpy.utils.time_from_frame(frame, *, fps=None, fps_base=None)

Returns the time from a frame number .

If fps and fps_base are not given the current scene is used.

Parameters: frame (int | float) – number.
Returns: the time in seconds.
Return type: datetime.timedelta

bpy.utils.register_manual_map(manual_hook)

bpy.utils.unregister_manual_map(manual_hook)

bpy.utils.register_preset_path(path)

Register a preset search path.

Parameters

path (str) –

preset directory (must be an absolute path).

This path must contain a “presets” subdirectory which will typically contain presets for add-ons.

You may call bpy.utils.register_preset_path(os.path.dirname(__file__)) from an add-ons __init__.py file. When the __init__.py is in the same location as a presets directory. For example an operators preset would be located under: presets/operator/{operator.id}/ where operator.id is the bl_idname of the operator.

Returns

success

Return type

bool

bpy.utils.unregister_preset_path(path)

Unregister a preset search path.

Parameters

path (str) –

preset directory (must be an absolute path).

This must match the registered path exactly.

Returns

success

Return type

bool

bpy.utils.register_classes_factory(classes): Utility function to create register and unregister functions which simply registers and unregisters a sequence of classes.

bpy.utils.register_submodule_factory(module_name, submodule_names)

Utility function to create register and unregister functions which simply load submodules, calling their register & unregister functions.

Note

Modules are registered in the order given, unregistered in reverse order.

Parameters

module_name (str) – The module name, typically __name__.
submodule_names (list[str]) – List of submodule names to load and unload.

Returns

register and unregister functions.

Return type

tuple[Callable[[], None], Callable[[], None]]

bpy.utils.register_tool(tool_cls, *, after=None, separator=False, group=False)

Register a tool in the toolbar.

Parameters

tool_cls (type[bpy.types.WorkSpaceTool]) – A tool subclass.
after (Sequence[str] | set[str] | None) – Optional identifiers this tool will be added after.
separator (bool) – When true, add a separator before this tool.
group (bool) – When true, add a new nested group of tools.

bpy.utils.make_rna_paths(struct_name, prop_name, enum_name)

Create RNA “paths” from given names.

Parameters

struct_name (str) – Name of a RNA struct (like e.g. “Scene”).
prop_name (str) – Name of a RNA struct’s property.
enum_name (str) – Name of a RNA enum identifier.

Returns

A triple of three “RNA paths” (most_complete_path, “struct.prop”, “struct.prop:’enum’”). If no enum_name is given, the third element will always be void.

Return type

tuple[str, str, str]

bpy.utils.manual_map()

bpy.utils.manual_language_code(default='en')

Returns: The language code used for user manual URL component based on the current language user-preference, falling back to the default when unavailable.
Return type: str

bpy.utils.script_path_user(): returns the env var and falls back to home dir or None

bpy.utils.extension_path_user(package, *, path='', create=False)

Return a user writable directory associated with an extension.

Note

This allows each extension to have its own user directory to store files.

The location of the extension it self is not a suitable place to store files because it is cleared each upgrade and the users may not have write permissions to the repository (typically “System” repositories).

Parameters

package (str) – The __package__ of the extension.
path (str) – Optional subdirectory.
create (bool) – Treat the path as a directory and create it if its not existing.

Returns

a path.

Return type

str

bpy.utils.script_paths(*, subdir=None, user_pref=True, check_all=False, use_user=True, use_system_environment=True)

Returns a list of valid script paths.

Parameters

subdir (str) – Optional subdir.
user_pref (bool) – Include the user preference script paths.
check_all (bool) – Include local, user and system paths rather just the paths Blender uses.
use_user (bool) – Include user paths
use_system_environment (bool) – Include BLENDER_SYSTEM_SCRIPTS variable path

Returns

script paths.

Return type

list[str]

bpy.utils.smpte_from_frame(frame, *, fps=None, fps_base=None)

Returns an SMPTE formatted string from the frame: HH:MM:SS:FF.

If fps and fps_base are not given the current scene is used.

Parameters: frame (int | float) – frame number.
Returns: the frame string.
Return type: str

bpy.utils.smpte_from_seconds(time, *, fps=None, fps_base=None)

Returns an SMPTE formatted string from the time: HH:MM:SS:FF.

If fps and fps_base are not given the current scene is used.

Parameters: time (int | float | datetime.timedelta) – time in seconds.
Returns: the frame string.
Return type: str

bpy.utils.unregister_tool(tool_cls)

bpy.utils.user_resource(resource_type, *, path='', create=False)

Return a user resource path (normally from the users home directory).

Parameters

resource_type (str) – Resource type in [‘DATAFILES’, ‘CONFIG’, ‘SCRIPTS’, ‘EXTENSIONS’].
path (str) – Optional subdirectory.
create (bool) – Treat the path as a directory and create it if its not existing.

Returns

a path.

Return type

str

bpy.utils.execfile(filepath, *, mod=None)

Execute a file path as a Python script.

Parameters

filepath (str) – Path of the script to execute.
mod (ModuleType | None) – Optional cached module, the result of a previous execution.

Returns

The module which can be passed back in as mod.

Return type

ModuleType

bpy.utils.expose_bundled_modules(): For Blender as a Python module, add bundled VFX library python bindings to sys.path. These may be used instead of dedicated packages, to ensure the libraries are compatible with Blender.