OpenSCAD boolean operations: difference, union and intersection

OpenSCAD boolean operations combine solids: union() merges them, difference() subtracts every later child from the first, and intersection() keeps only the volume they all share. This is called constructive solid geometry (CSG), and almost every printable part is a stack of these three operations.

The three boolean operations at a glance

union(): merge solids into one

union() joins its children into one solid. Overlapping volume is merged and the internal faces disappear:

union() {
  cube([20, 20, 4]);
  translate([10, 10, 0]) cylinder(h=14, d=8, $fn=48);
}

Top-level objects in the PrintPal editor

Desktop OpenSCAD unions everything at the top level of a file for you when it renders. The PrintPal editor runs OpenSCAD with the experimental lazy-union feature, which skips that step: separate top-level objects are exported as separate, overlapping bodies. This file gives you two shells that pass through each other, not one solid:

cube([20, 20, 4]);
translate([10, 10, 0]) cylinder(h=14, d=8, $fn=48);

difference(): cut holes and pockets

difference() keeps its first child and subtracts every child after it. A through hole in a plate looks like this:

difference() {
  cube([40, 40, 4]);                          // base: the first child
  translate([20, 20, -1])
    cylinder(h=6, d=6, $fn=48);               // cutter: starts 1 mm below, ends 1 mm above
}

Order matters. Swap the two children and OpenSCAD keeps the cylinder minus the plate, which leaves two 1 mm discs where the cylinder stuck out above and below:

difference() {
  translate([20, 20, -1]) cylinder(h=6, d=6, $fn=48);
  cube([40, 40, 4]);
}

Why cutters must overshoot: coplanar faces

When a cutter's face lies exactly on a face of the part, the two surfaces are coplanar. Whether the cut goes through then depends on floating-point rounding. Exact whole numbers on axis-aligned shapes often work, but tiny errors leave an invisible skin or ragged geometry. Here 0.1 * 3 is really 0.30000000000000004, so the plate is a hair taller than the 0.3 mm cutter and the hole stays closed:

t = 0.1 * 3;   // 0.30000000000000004
difference() {
  cube([20, 20, t]);
  translate([10, 10, 0]) cylinder(h=0.3, d=6, $fn=32);
}

Cutter faces flush with the part: a skin can survive, and the preview flickers (z-fighting).

Start the cutter 1 mm below and make it 2 mm taller than the plate, as in translate([x, y, -1]) cylinder(h=t + 2, …).

The same rule applies to unions: let a boss sink a little into the plate rather than touching it at exactly one face. Rotated parts make the problem worse because their coordinates are never exact.

Debug cutters with modifier characters

Cutters are invisible once they have done their job, which makes a misplaced one hard to find. Modifier characters go in front of any shape or operation:

difference() {
  cube([40, 40, 4]);
  #translate([20, 20, -1]) cylinder(h=6, d=6, $fn=48);
}

intersection(): keep the overlap

intersection() keeps only the space that is inside every child. A sphere intersected with a cylinder that starts halfway up gives a domed button cap:

intersection() {
  sphere(r=12, $fn=64);
  translate([0, 0, 6]) cylinder(h=10, d=26, $fn=64);
}

Intersecting with a large cube is the quickest way to split a part so each half prints flat on the bed:

intersection() {
  sphere(r=20, $fn=64);                       // stand-in for your part
  translate([-50, -50, 0]) cube([100, 100, 50]);
}   // keeps the top half

Practical boolean patterns

Open-top box (shell)

Subtract a smaller block that starts one wall thickness in and pokes out of the top. For printing, 1.2 mm is a sensible minimum wall with a 0.4 mm nozzle; see the 3D printing design guide.

wall = 2;
size = [40, 30, 25];
difference() {
  cube(size);
  translate([wall, wall, wall])
    cube([size[0] - 2*wall, size[1] - 2*wall, size[2]]);
}

Plate with screw bosses

Union the bosses with the plate first, then cut every hole in one difference() so the holes run through both:

holes = [[5, 5], [35, 5], [5, 25], [35, 25]];
difference() {
  union() {
    cube([40, 30, 4]);
    for (p = holes)
      translate([p[0], p[1], 0]) cylinder(h=12, d=7, $fn=32);
  }
  for (p = holes)
    translate([p[0], p[1], -1]) cylinder(h=14, d=3.4, $fn=32);
}

Countersunk holes

A 90° countersink is a cone whose depth is half the difference between the head and shank diameters. Set head_d to your screw head plus a little clearance:

module csk_hole(d=3.4, head_d=6.5, plate_t=4) {
  head_h = (head_d - d) / 2;                        // depth of a 90° countersink
  translate([0, 0, -1]) cylinder(h=plate_t + 2, d=d, $fn=32);
  translate([0, 0, plate_t - head_h])
    cylinder(h=head_h + 0.01, d1=d, d2=head_d + 0.02, $fn=48);
}

difference() {
  cube([30, 20, 4]);
  translate([8, 10, 0])  csk_hole();
  translate([22, 10, 0]) csk_hole();
}

Cutaway view

Subtract a big block to look inside a part while you design it:

difference() {
  difference() {                              // your part: a hollow tube
    cylinder(h=30, d=20, $fn=64);
    translate([0, 0, 2]) cylinder(h=30, d=16, $fn=64);
  }
  translate([0, -50, -1]) cube([50, 100, 50]); // remove the +X half to look inside
}

render() and performance

render(convexity=4)
  difference() {
    cube(20, center=true);
    sphere(r=13, $fn=64);
  }

In desktop OpenSCAD, render() computes its child as a real mesh during the F5 preview and caches it, which speeds up previews of heavy booleans and fixes preview glitches. convexity only helps the preview draw shapes correctly: it is the most surfaces a ray through the object can cross. The PrintPal editor always does a full render with the fast Manifold engine, so render() makes no visible difference there. Lowering $fn while you design is the bigger speed win; see 3D primitives.

Ask the CAD Agent for boolean-heavy parts

The CAD Agent writes these unions and differences for you. Give it finished sizes, wall thickness and where each cut goes.

Frequently asked questions

Tools for thisAll tools

CAD AgentDescribe a part in plain English and get editable OpenSCAD with a live 3D preview and STL or 3MF export.

Watch it doneVideo library

0:57 Parametric CAD from a photo using PrintPalTools 0:25 turn text to mechanical parts for 3D printingTools 2:12 CAD Agent, but the Prompts DoubleIdeas

Was this article helpful?

Yes Not really

Send

Thanks! We read every note and use them to decide what to update next.