openSCAD tutorial

Making a mechanical part requires a drawing. It started with paper, and the first CAD programs used exactly the same style. There are even standard squares on the drawings so that each drawing is identified. All this is useful when you start going into production in large corporations. However, when you start making a new mechanical piece, you may want other methods.

3D CAD methods allow you to see the whole piece as it is. You can also twist and turn it. In advanced software, you can also simulate movement. In all cases, you draw the pieces using a graphical interface. This is great for making boxes and cylinders, but when you want to make more complex shapes, you may need mathematical methods.

Enter a standard way to describe any material with commands.

What makes openSCAD so special?

In openSCAD, you do not draw anything with your pointer or pen. You code the entire piece with commands and functions. This is awkward for mechanical engineers, but for programmers, you have another situation. Apart from personal preference, you also have the advantage of precision. When you design it with code, you have the precision there in the code.

The most powerful feature of openSCAD is binary operations. You can use binary operators to put pieces together or cut material out. It is easy to make a cube with a hole in the centre by retracting the cylinder from the cube. Some of these operations are available in other CAD software, but it falls naturally to use them in openSCAD.

What are your project needs?

After you have put your design on a napkin, you may think that you need to see what is happening when you try to make it a full design. Don’t worry; there is a preview window for you to look at while you code. Once you understand the basic ideas, you will know if it is the best fit for your project.

In short, if you want to create small pieces that have complex shapes, you should try openSCAD. For full equipment and mechanical systems, you want to use more advanced graphical applications. Having said that, it is all a matter of taste. You can make complicated shapes with just code, would you consider coding an entire car?


OpenSCAD, available in your standard repositories for most distributions, can also be installed using a snap and AppImage. Interesting is that you also have a second package that includes screws, gears, and generic shapes. The newest package is in the openscad-nightly snap.

sudo apt install openscad
sudo snap install openscad-nightly

If you want to use the included screws that come as a separate package, use your distribution’s repositories.

sudo apt install openscad-mcad

Using the included parts is another matter, covered further down.

Several standard shapes

The principles of scripting CAD is that you have a few standard geometric shapes. You use these shapes and combine them into more complex shapes. The standard shapes are circle, square, and polygon for 2D. For 3D, you have a sphere, cube, cylinder, and polyhedron. By using some of these to build and others to cut, you can create very complex shapes.

There is also a text function that creates a 2D text. When you need to create drawings for further processing, you can use the projection command. This command cuts a 3D shape along a plane so you can transfer it to a drawing. You can also add shapes from other programs or even images, using the import command. This also works with 3D-shapes.

In addition, you can extrude shapes from existing objects.


By default, you create all pieces at the centre point of the grid in all dimensions. This makes them all overlap. Once you have a number of shapes, you want to have them placed in the right spot and rotated. These functions are the simple ones, translate puts the object in another place. The rotate command rotates the object or child objects. You also have the mirror function, which creates a copy of the object mirrored around the given axle.

The other transformations need examples to explain. In short, hull creates the outer lines of many shapes. Try with two circles and combine them with hull(). Or the code below.

translate([-10,0,0]) {
   hull() {    
       cylinder(30, 5, 1);

The Minkowski operation is usually used to create edges; if you want them rounded, use a sphere.

Boolean operations

Many pieces cannot be created with only squares, cylinders, and spheres. The first thing you can do is to combine and cut many shapes into a single shape. You use boolean operators to do this. They are union, difference, and intersection.

union() {
   cube([35, 5, 2], center = true);
   cylinder(h = 2, r = 5, center = true );

In the code above you get a single piece that has a bulb at the centre. To make a tube, you take the difference between one cylinder and another.

difference() {
   cylinder(h = 15, r1 = 30, r2 = 30, center= true );
   cylinder(h = 15, r1 = 25, r2 = 25, center = true) ;

As we move on, you will use these and more. Here is an intersection example.

       cylinder( h = 40, r = 4, center = true);
   translate(5,5,5) {
       cylinder( h = 40, r = 6, center = true);

Intersection leaves only the overlapping stuff; you can create many shapes using this method.

For Loops

Many of your designs will have the same piece many times, consider a patio. They are usually made of several planks with gaps between them. In this case, you make one plank and just iterate over them with a for loop.

gap = 8;
plank_width = (bed_width / 4) - gap;
num_planks = 4;

for(plank_x_pos = [0:1:num_planks - 1])
   translate([plank_width*plank_x_pos + gap * plank_x_pos,0,0])

Without the for loop, you would have written the cube and translate statements four times. You also would have had to calculate how far out the next plank would go. Even with only four pieces, this solution looks much easier. In the example, you can also see variables that need to be set. All variables are set at compile-time, this is important since you may run into debugging problems if you think of them as values in other programming languages. As you will see later, you can also make the whole patio a module.


Included in openSCAD, you have a few mathematical functions available. Supported features are most trigonometric functions, rounding in different ways and logarithmic function. You can see an example below.


The above function creates a long straight row of cylinders of differing height. The main functions are connected to trigonometry. However, with random, rounding functions and the standard operators, you can create pretty much everything. There is also support for vectors, matrices, and square root. Even with these functions, you can get really far. However, they do not cover everything you can imagine; instead, you can create functions.

Modules & Functions

You have many modules included in the openSCAD install. However, you can also download other libraries. In your distribution, you probably find MCAD, also called openscad-mcad. To install under Ubuntu.

$ sudo apt install openscad-mcad

Inside this package, you find both modules and functions. Before you start any project, look around for libraries and modules. There is already a library of screws, and that is just the beginning. Missing a part of your design? Make your own modules; you use them to make new pieces. When you use parameters, you can make many versions out of them. The best way to create a module is to make the design as a separate file, figure out what needs to be dynamic, and add ‘module’ around the piece.

To use a module, you call it by its name. Since many modules come in separate files, you must put an include statement at the top of your file. Pay attention to the difference between the “include” statement and the “use” statement. If you want everything in a file to execute, you “include” it, if you want modules and functions defined only, “use” the file. To make sure you can use the modules, you must put them in your model’s current directory or one of the search paths.

First, let’s look at a few you can download and use.


In the package from the earlier section, you can find a lot of things. One group are screws! You can try them out by loading them into the application and calling the module. In the MCAD Library, you can find many screws. There are many other collections from other sources. To use a screw, create a file that contains the include statement for the module you need. Now, anywhere you want to use the module, you can use the name of the module to create your screw.

include <screw.scad>;
ball_groove(12, 40, 2);

This is a screw that can fit a ball. You can also find nuts_and_bolts_scad, which defines metric screws and bolts. The designers used a website where you can find bolts and created a method for you to use. Another example is a hole for a bolt.

include <nuts_and_bolts.scad>

difference() {
    cube([12,16,20],center = true);
        boltHole(8, length = 300);

The above code creates a hole large enough for the M8 bolt, this example creates a cube and cuts out two cylinders of two sizes. That is not very complicated, but the complexity quickly grows when you use other components. Add the screws to parametric boxes, and you can see how a library helps.

Making a cart

To make any construction of any complexity, you will need to make one piece at a time. Later, you combine them with each other. As we have mentioned earlier, you can use modules and functions. The best way to get started is to decide where you need to set variables. For a simple cart, you need height, wheelbase, and length. You need to set the values in one place and use them to make the parts fit around the design. You may need more values, but don’t put all of them when you start out. When you start a new project, you will not have all the parts ready, so be prepared to change things around.

wheelbase = 150;
cartlength = wheelbase * 1.2;
cartwidth = 50;
wheeldiameter = 25;
suspensionheight = (wheeldiameter/2) + 5;

        cylinder(r = wheelradius, 10, center = true);

        cylinder(r = wheelradius, 10, center = true);

The code shows the code for the first two wheels. If you think a little about it, you can probably make the rear wheels. To add the flak, the surface where all the stuff goes, you just add a cube. Use the variables you put in the code.

translate([0, 0, suspensionheight])
cube([cartlength, cartwidth,10], center = true);

This flak is on the same height as the wheels, though, so we took care of that with the suspension height value. The translated statement affects what is directly after it. Note that there is no semi-colon at the end of a line. When the statements inside become long, you use curly braces around it.

Now, you need to add axles and suspension. The axles can be simple cylinders that go between the wheels. You place them the same way you did the wheels using rotate and translate. In fact, the best is to use the same values.

        cylinder(r = wheelradius * 0.25 , h = (cartwidth * 2) + 15, center = true);

The code here puts the front axle in place. The rear axle, I leave you the reader to figure out. We can solve the suspension in many ways. In this case, we will keep it simple.

// Suspension
translate([wheelbase/2, 0, suspensionheight ])
        difference() {
            cylinder(r = suspensionheight, 10, center = true );
            cylinder(r = suspensionheight - 5, 11, center = true );
            cube([102, suspensionheight/6, 12], center = true);

    translate([suspensionheight, 0, 0])
        cylinder(r = suspensionheight/3, h = 12, center =true);

    translate([-suspensionheight, 0, 0])
        cylinder(r = suspensionheight/3, h = 12, center =true);


This code creates a very crude suspension; it only uses cylinders, so it will not be the best when you start using it. It does illustrate one way of creating designs form the primitives; cylinder, cube, and well, that’s it for this model. As you progress, you will make each piece a module and place those pieces.

The code for the cart is available at! Further developments may come later.


In the earlier part, you used only circles. Any designs using only those primitives will not be the best for all applications. You need to create good looking and efficient designs. The solution is mathematics! To add this, you should start by using other people’s libraries.

There are a large number of libraries built by smart people in the community. The people who build are users who solve their problems and then graciously shared it with everyone else. Thanks to all of you! A good example is dotSCAD; for the suspension example, you can find a B├ęzier curve.

Exporting to other software

Once you have a decent design, you may want to use it in another software. You can export to stl, dwg, and a host of other formats. Your 3D-printing enthusiasts can use the stl files directly in your slicer programs.


Another exciting alternative is ImplicitCAD. This software is very much in development. You have to run its command line, and it requires Haskell on your system. Most standard installs do not have Haskell!


At first, glance, using openSCAD is very hard. Getting past the learning curve is a bit of a struggle, but it is worth it for many users. Thanks to the projects to contribute to the project. You have many features available at the end of a git command. Just getting through the basics of creating mechanical designs through code changes the way you think about shapes. This is beneficial even if you will keep using point and click to make your other projects.

About the author

Mats Tage Axelsson

I am a freelance writer for Linux magazines. I enjoy finding out what is possible under Linux and how we can all chip in to improve it. I also cover renewable energy and the new way the grid operates. You can find more of my writing on my blog.