Using `nodebpy`

Using nodebpy inside of your own add-ons & projects.

The package is available on PyPI here. You can install it and use it in your own projects using pip or your preferred package manager, I recommend uv.

pip install nodebpy
uv add nodebpy

This will allow it to be shipped with add-ons, following their guidelines on how to bundle .whl files or vendoring.

nodebpy should be forward-compatible, but likely backwards incompatible with older versions of Blender, as new nodes are added the code will break if trying to use them in older versions of Blender.

Versioning `nodebpy`

For clarity around which versions of Blender nodebpy supports, it will be versioned with a modified semantic versioning scheme.

The scheme will be: BLENDER_VERSION.MINOR_VERSION.PATCH_VERSION. For example Blender 5.2.0 would be 520.0.0. Major version changes that are compatible with Blender 5.2.0 would be 520.X.Y, where extra features could be added in 520.1.0 and a bug fix or patch could be added in 520.0.1. Version 520.X.Y should be forward compatible with Blender 5.3+, but incompatible with Blender 5.1 and earlier.

Development and updates will mostly happen on the later versions as Blender adds new updates and features, but some fixes and patches may be backported to older versions as needed.

Using multiple versions

If you use nodebpy in your add-on you likely support multiple versions of Blender.

Each version of nodebpy will target a specific Blender release, but you can import multiple versions if you vendor the package inside of your add-on.

YourAddon/
├── lib/
|   ├── __init__.py (empty)
│   ├── nodebpy/
│   │   ├── __init__.py
│   │   ├── _520/
│   │   │   ├── src/nodebpy (5.2.0)
│   │   ├── _530/
│   │   │   ├── src/nodebpy/ (5.3.0)
└── ...

lib/nodebpy/__init__.py

import bpy

_v = bpy.app.version

if _v == (5, 2, 0):
    from ._520.src.nodebpy import *
elif _v >= (5, 3, 0):
    from ._530.src.nodebpy import *
else:
    raise ImportError(f"Unsupported Blender version: {_v}")

This way you can import the correct version of nodebpy based on the Blender version at runtime.

It’s up to your own usual versioning code to ensure that code used is compatible with the right Blender versions, but you should be able to just impotr from .lib.nodebpy like regularly using the package.

from bpy.types import GeometryNodeTree
from .lib.nodebpy import geometry as g

def default_tree(count: int = 10) -> GeometryNodeTree:
    with g.tree("Default Tree Name") as tree:
        (
            tree.inputs.integer("Count", count)
            >> g.Points(position=g.RandomValue.vector())
            >> g.InstanceOnPoints(instance=g.IcoSphere())
            >> tree.outputs.geometry("Result")
        )

    return tree.tree


default_tree()

graph LR
    N0("Group Input"):::default-node
    N1("Random Value"):::converter-node
    N2("Points"):::geometry-node
    N3("Ico Sphere"):::geometry-node
    N4("Instance on Points"):::geometry-node
    N5("Group Output"):::default-node
    N0 -->|"Count->Count"| N2
    N1 -->|"Value->Position"| N2
    N2 -->|"Points->Points"| N4
    N3 -->|"Mesh->Instance"| N4
    N4 -->|"Instances->Result"| N5

Versioning nodebpy

Using multiple versions

Versioning `nodebpy`