For including code from external files in OpenSCAD, there are two commands available:

• include <filename> acts as if the contents of the included file were written in the including file, and
• use <filename> imports modules and functions, but does not execute any commands other than those definitions.

Library files are searched for in the same folder as the design was opened from, in the library folder of the OpenSCAD installation, and in folders given by the OPENSCADPATH environment variable. You can use a relative path specification to either. If they lie elsewhere you must give the complete path. Newer versions have predefined user libraries, see the OpenSCAD_User_Manual/Libraries page, which also documents a number of library files included in OpenSCAD.

Wildcards (e.g. include <MCAD/*.scad>) can not be used to include multiple files.

include <filename>

When file A includes file B, it is almost exactly as if B was dropped at that point in A. Everything in B is visible to A, and everything in A is visible to B.

v = 1;

include <B.scad>
v = 5;
echo(v=v);

ECHO: v = 5

a = 1;
b = 2;

include <B.scad>
a = b + 1;
echo(a=a, b=b);

WARNING: Ignoring unknown variable "b" in file a.scad, line 2
WARNING: undefined operation (undefined + number) in file a.scad, line 2
ECHO: a = undef, b = 2

var = include <filename>;

Because include is functionally equivalent to dropping an included file into the spot in the parent file where the include statement appeared (replacing the include statement with the new file) it is possible to assign data in an external file to a local variable name.

For example, suppose the file data.txt contains a comma-delimited list of numbers:

8, 6, 3, 8, 6, 4, 5, 99, 8, 1, 3, 5

Then in OpenSCAD, putting the include inside array brackets imports the data as an OpenSCAD array:

numlist = [ include <data.txt> ];
echo(numlist);

produces:

ECHO: [8, 6, 3, 8, 6, 4, 5, 99, 8, 1, 3, 5]

One would think that it's possible to import CSV data in a similar fashion, by knowing the number of columns in the CSV file in advance, and split the array into a list of row arrays, but this wouldn't work. CSV allows for empty data between commas, which are ignored by OpenSCAD, causing differences in the lengths of each row. It is best to preprocess a CSV file into a more compatible format before including it.

Another example: suppose the file cube.poly contains an array describing a polyhedron for a cube, with a list of 8 vertices followed by a list of 6 faces.

[
    [ // vertices
        [37.5,67.5,0], [37.5,42.5,0], [12.5,42.5,0], [12.5,67.5,0],
        [37.5,67.5,25], [12.5,67.5,25], [12.5,42.5,25], [37.5,42.5,25]
    ],
    [ // faces
        [3,2,1,0], [7,6,5,4], [1,7,4,0], [2,6,7,1], [3,5,6,2], [5,3,0,4]
    ]
]

Because include replaces itself with the included file, one can assign the include to a variable name:

cube_poly = include <cube.poly>;
vertices = cube_poly[0];
faces = cube_poly[1];
polyhedron(vertices, faces);

When using this trick to assign the contents of an included file to a variable name, avoid doing this with .scad files. Your data files should have some other extension, because the included file should contain data rather than OpenSCAD source code.

use <filename>

When file A uses file B:

• A can see B's modules and functions.
• A cannot see B's global variables.
• B cannot see A's global variables.
• B cannot see A's modules and functions.
• B's top-level module invocations are not executed.
• B's top-level assignments are executed on every call from A to B. (This can be useful if they are dependent on $ variables defined by A, or can be a performance problem.)

use <filename> is allowed only at the top level of a file.

Example "Ring Library"

A library file for generating rings might look like this:

ring.scad:

module ring(r1, r2, h) {
    difference() {
        cylinder(r = r1, h = h);
        translate([ 0, 0, -1 ]) cylinder(r = r2, h = h+2);
    }
}

ring(5, 4, 10);

Including the library using

include <ring.scad>
rotate([90, 0, 0]) ring(10, 1, 1);

would result in the example ring being shown in addition to the rotated ring, but

use <ring.scad>
rotate([90, 0, 0]) ring(10, 1, 1);

shows only the rotated ring.

Additional Notes