About this guide

This guide is for architects and other building professionals who are moving to Bonsai, particularly those arriving from Revit or ArchiCAD, and it tries to answer one question that the existing documentation does not: what kind of thing is this?

The official documentation is task-shaped, and good at what it does - install this, click here, make a wall. What it assumes is that you already understand the arrangement you have stepped into: that the file is the project, that the model is a graph of standard objects, that drawings come out of the model rather than sitting beside it. Somebody arriving from a system built on quite different assumptions has to reconstruct all of that from the tasks, and most people give up somewhere in the middle.

So this is not a tutorial and not a reference. It is a short description of the shape of the thing, with links out to the documentation wherever there is detail worth having.

It is written to four rules: one lesson per page, describe the model rather than the buttons, link outward rather than expanding, and stay readable in a terminal browser.

Bonsai and BlenderBIM

There is one add-on with two names. It was the BlenderBIM Add-on until August 2024, when it was renamed Bonsai. This was a rename and nothing more - not a fork, not a rewrite, not a change of direction. Same software, same people, same repository.

The old name is still about, and will be for years. Tutorials, forum threads and videos that say BlenderBIM are describing this software accurately, and are worth reading. The name also lingers in packaging, which is where it will outlast everything else: the Chocolatey package is still called blenderbim-nightly, in a directory that has itself been renamed to bonsai.

If you are searching for help with something, it is worth trying both names.

Currency

Bonsai moves quickly, and that is the central problem for a guide like this one.

The response has been to describe things that change slowly and to refuse to describe things that change fast. There are no screenshots, no click-by-click instructions, and no inventories of panels, because those are precisely the parts that rot. There are no version numbers either, since a guide that announces which release it covers has dated itself on the day it is published.

What is here instead is the model: the file, the schema, containment, types, representations, queries. Those are properties of IFC and of the way Bonsai is built, and they change on a scale of years rather than months.

Factual claims about Bonsai were checked against its source code rather than against memory or against the documentation, which in places describes an older arrangement. Some of them will still go out of date. Reports of that are the most useful corrections this guide can receive.

Tools used creating this guide

The site is a set of Markdown files built into static HTML with Hugo. Nothing is dynamic and there is no server doing anything clever; the whole guide is a few dozen kilobytes of text.

The text is set in XCharter, a free descendant of Matthew Carter’s Charter, served from this site. There is no JavaScript, and no page here asks anything of anybody else’s server, so nothing on this site can watch you read it.

AI tools were used in the writing of this guide. The factual claims in it were checked against Bonsai’s source code, as described above.

The pages are written to be readable in a terminal browser, which is one of the rules above and a reasonable proxy for being readable by anything at all.

Corrections

Corrections and suggestions are welcome, and particularly reports of things that have quietly stopped being true, or of links that have rotted. The address is at the foot of every page.

Copying

This guide is released under the GNU Free Documentation License.

The typeface is not the guide’s to license. It is redistributed here under Bitstream’s own permission, which travels with the files in /fonts/LICENCE.txt.

Last updated 5 September 2026.