BOSL2: What the Belfry OpenSCAD Library Actually Changes in Your Models

Why a plain OpenSCAD model gets hard to edit

Native OpenSCAD gives you cubes, cones and spheres, and it gives you translate and rotate. That is enough for a single object. It stops being enough once a model has parts that must sit on other parts, because every position is a coordinate you maintain by hand. Move the base and every child coordinate has to move with it.

BOSL2 targets exactly that. The README describes attachments as the feature that lets you position components relative to other components, so instead of tracking positions and orientations you place something on the TOP of something else, or aligned to the RIGHT. The library also covers ground that is genuinely awkward in native OpenSCAD: rounding and filleting, which the README calls hard in OpenSCAD, and geometrical operations on 2d point lists, which it calls paths or regions. In OpenSCAD, operations happen on geometry and information can never be extracted from geometry; BOSL2 works on the point lists themselves.

The audience is therefore narrow and specific. It is for people who already write OpenSCAD and have hit the wall where a model is a dozen positioned parts rather than one shape. It is not a modelling application and it does not replace the OpenSCAD language.

Attachments, VNFs and the rest of the mechanism

The organising idea is the attachment. A shape carries anchor points, and you place one shape relative to another by naming the anchor rather than by computing a transform. The README points to a dedicated Attachments Tutorial in the wiki for the full introduction, which is a fair signal that this is a system with its own vocabulary rather than a single function call.

Two data structures recur. A path or region is a 2d point list, and the library offers operations on them such as round_corners to round a path with corners, plus intersection and offset in regions.scad. A VNF, short for Vertices 'N' Faces, is how BOSL2 refers to a polyhedron described by a vertex list and a face list. The README is explicit that ensuring a valid polyhedron by hand is tedious, and that the library provides tools to create VNFs that are guaranteed to be valid, along with some limited geometrical operations on them.

Around that core sit the parts the README lists: shorthands where up(z) replaces translate([0,0,z]), complex object support through path_sweep and skin and vnf_vertex_array, beziers and NURBS, metaballs for organic surfaces, texturing that can replace the base object with repeating copies of a texture element or emboss an image, and a parts library with gears, threading, bottle caps, pipe fittings, screws, clips, hinges and dovetail joints. The repository layout matches this: the top level is a flat set of .scad files, one per domain, with std.scad as the aggregate include. This is a library you include, not a service you run.

Installing BOSL2 and getting an attachment to work

The README states a hard version floor: OpenSCAD 2021.01 or later. Check that first, because nothing else matters if your OpenSCAD is older. The library is distributed as source files from the repository, with the default branch named master, and the README points to the project wiki as the documentation home.

The conventional OpenSCAD route is to place the library where OpenSCAD looks for libraries, then include std.scad in your model. The exact directory differs by platform and the README does not spell it out, so follow the wiki rather than guessing a path. The README does not give an install command, so there is none to copy here.

Once the include resolves, the smallest useful thing to try is an attached pair of shapes, which is the feature the README leads with. The wiki's Attachments Tutorial is the reference for the anchor names; the point of the exercise is that no coordinate appears in the call. The README gives no worked attachment snippet, so read the tutorial and the examples/attachments.scad example in the repository rather than copying a listing from this page.

The second thing worth trying is rounding, since that is the other problem the README singles out. The library provides cuboid() for a cube with rounded edges and offset_sweep() for rounding the ends of a linear extrusion. If your OpenSCAD renders the attached cylinder sitting on the top face of the cuboid without you supplying a z coordinate, the include and the library path are both correct. After that, browse the examples/ directory in the repository, which holds complete models including attachments.scad and BOSL2logo.scad.

Beta status, BOSLv1 breakage and the cost of a large include

The README is unusually blunt about two things, and both matter more than any feature list. First: BOSL2 is beta code and the code is still being reorganized. Second: code written for BOSLv1 will not work with BOSL2. There is a bosl1compat.scad file at the top level, but the README does not present it as a migration guarantee, and the existence of a compatibility file is not the same as a supported upgrade path. If you have a BOSLv1 model that works, porting it is a rewrite of the parts that touch the library, not a version bump.

The beta label has a practical consequence for anyone pinning dependencies. Releases are frequent, with v2.0.762, v2.0.757 and v2.0.755 appearing on consecutive Sundays in the release list. Frequent releases are good for fixes and bad for API stability, and the README's own note that the code is still being reorganized tells you which way the risk runs. Pin a tag if you need a model to keep building unchanged.

The other limitation is scope. The README describes operations on 2d paths and regions and some limited operations on three dimensional data, and it describes VNF operations as limited too. If your work needs general boolean or geometric operations on solid meshes, this is not the tool for it. The library also does not remove the need to understand OpenSCAD: it changes what you write, not what the language can represent.

BOSL2 against writing the transforms yourself

The real alternative is not another library. It is native OpenSCAD with your own helper modules, or a different modelling tool entirely.

Take the attachment case. In native OpenSCAD you would write a translate and a rotate for the child, and you would keep those numbers correct as the parent changes. BOSL2 replaces that with a named anchor, at the cost of learning the anchor vocabulary and depending on the library's definition of where TOP is. The trade is real in both directions: hand-written transforms have no version risk and no include, while attachments remove a whole class of arithmetic errors in multi-part models.

For rounding, the same shape of trade appears. Native OpenSCAD can approximate a rounded box with hull() over spheres and cylinders, which is workable for a box and painful for anything with selective edges. BOSL2 offers edge_profile() to apply mask profiles to chosen edges of a cubic shape, and prism_connector() to create filleted prisms between objects. That is a capability difference, not a convenience difference, and it is the part of the library least likely to have a native substitute.

The other alternative is to leave OpenSCAD. If your models are organic or sculpted rather than parametric, the README's own list of what BOSL2 adds, prisms, tubes, threads, gears, hinges, is a list of engineering parts. A subdivision modeller is a better fit for that work, and BOSL2 will not close the gap.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-27, so the project is under current development rather than dormant. That is the good news for anyone worried about adopting an abandoned library. It is also the source of the upgrade cost: with releases landing weekly and the README stating the code is still being reorganized, upgrading means re-reading the wiki pages for the modules you use, not just copying a new folder over the old one.

The licence is BSD-2-Clause, a permissive licence that the LICENSE file at the repository root carries. BSD-2-Clause is generally read as permitting use in closed and commercial work with the copyright notice and licence text retained, but the file itself is the authority and this is not legal advice. If your organisation has rules about which licences may enter a product, the identifier to check against that list is BSD-2-Clause, and the notice obligations are short enough to read in full.

One maintenance detail worth noting: the project ships its own documentation tooling. The repository root contains .openscad_docsgen_rc and .openscad_mdimggen_rc alongside WRITING_DOCS.md and TESTING.md, and there is a scripts/ directory. That means the wiki pages are generated from the source rather than hand-maintained, which is why the README links into wiki pages named after the .scad files. It also means a contributor adding a module is expected to follow the documentation conventions in WRITING_DOCS.md, and that the wiki is the primary reference rather than the README.

Editorial conclusion

Adopt BOSL2 if you are building multi-part OpenSCAD models and want attachment-based positioning instead of hand-computed translate and rotate calls, and accept that the library is beta and reorganising. Do not adopt it if you have a working BOSLv1 codebase, because the README states that code written for BOSLv1 will not work with BOSL2, or if you are on an OpenSCAD older than 2021.01. Before committing, check that your installed OpenSCAD meets that version floor, run one attachment example from the wiki against your own model, and confirm the modules you rely on in the wiki pages rather than assuming the API is settled.

Frequently asked questions

Official sources

1. BelfrySCAD/BOSL2 on GitHub
2. License: BSD-2-Clause
3. Project website
4. README
5. Releases