Getting Started V2.9.

4-5-g9a3aa17b34, 25
Jan 2025
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 ii

Contents

1 About LinuxCNC 1
1.1 The Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 The Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.1 IRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.2 Mailing List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.3 Web Forum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.4 LinuxCNC Wiki . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.5 Bug Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 System Requirements 4
2.1 Minimum Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 Kernel and Version requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.1 Preempt-RT with linuxcnc-uspace package . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.2 RTAI with linuxcnc package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.3 Xenomai with linuxcnc-uspace package . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.4 RTAI with linuxcnc-uspace package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Problematic Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3.1 Laptops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3.2 Video Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Getting LinuxCNC 7
3.1 Download the image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.1 Normal Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.2 Download using zsync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1.3 Verify the image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Write the image to a bootable device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2.1 Raspberry Pi Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.2 AMD-64 (x86-64, PC) Image using GUI tools . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.3 Command line - Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 iii

3.2.4 Command line - MacOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.3 Testing LinuxCNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.4 Installing LinuxCNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5 Updates to LinuxCNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.6 Install Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.7 Alternate Install Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.7.1 Installing on Debian Bookworm (with Preempt-RT kernel) . . . . . . . . . . . . . . . 12
3.7.2 Installing on Debian Bookworm (with experimental RTAI kernel) . . . . . . . . . . . 13
3.7.3 Installing on Raspbian 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 Running LinuxCNC 14
4.1 Invoking LinuxCNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2 Configuration Launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3 Next steps in configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.4 Simulator Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5 Configuration Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5 Updating LinuxCNC 18
5.1 Upgrade to the new version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.1.1 Apt Sources Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.2 Upgrading to the new version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.1.2.1 Debian Buster, Bullseye and Bookworm . . . . . . . . . . . . . . . . . . . . . 20
5.1.3 Ubuntu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2 Updating without Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.3 Updating Configuration Files for 2.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.3.1 Stricter handling of pluggable interpreters . . . . . . . . . . . . . . . . . . . . . . . . 21
5.3.2 Canterp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.4 Updating Configuration Files (for 2.9.y) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.4.1 Spindle limits in the INI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.5 New HAL components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.5.1 Non-Realtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.5.2 Realtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.6 New Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6 Glossary 24

7 Legal Section 30
7.1 Copyright Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.2 GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 iv

The LinuxCNC Team

This handbook is a work in progress. If you are able to help with writing, editing, or graphic prepara-
tion please contact any member of the writing team or join and send an email to [email protected]
Copyright © 2000-2020 LinuxCNC.org
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free
Documentation License, Version 1.1 or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is
included in the section entitled ”GNU Free Documentation License”.
If you do not find the license you may order a copy from:
Free Software Foundation, Inc.
51 Franklin Street
Fifth Floor
Boston, MA 02110-1301 USA.

(The English language version is authoritative)

LINUX® is the registered trademark of Linus Torvalds in the U.S. and other countries. The registered
trademark Linux® is used pursuant to a sublicense from LMI, the exclusive licensee of Linus Torvalds,
owner of the mark on a world-wide basis.
The LinuxCNC project is not affiliated with Debian®. Debian is a registered trademark owned by
Software in the Public Interest, Inc.
The LinuxCNC project is not affiliated with UBUNTU®. UBUNTU is a registered trademark owned
by Canonical Limited.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 1 / 34

Chapter 1

About LinuxCNC

1.1 The Software

• LinuxCNC (the Enhanced Machine Control) is a software system for computer control of machine
tools such as milling machines and lathes, robots such as puma and scara and other computer
controlled machines up to 9 axes.

• LinuxCNC is free software with open source code. Current versions of LinuxCNC are entirely li-
censed under the GNU General Public License and Lesser GNU General Public License (GPL and
LGPL)
• LinuxCNC provides:

– easy discovery and testing without installation with the LiveCD

– easy installation from the Live CD
– easy to use graphical configuration wizards to rapidly create a configuration specific to the ma-
chine
– directly available as regular packages of recent releases of Debian (since Bookworm) and Ubuntu
(since Kinetic Kudu)
– a graphical user interface (actually several interfaces to choose from)
– a graphical interface creation tool (Glade)
– an interpreter for G-code (the RS-274 machine tool programming language)
– a realtime motion planning system with look-ahead
– operation of low-level machine electronics such as sensors and motor drives
– an easy to use breadboard layer for quickly creating a unique configuration for your machine
– a software PLC programmable with ladder diagrams

• It does not provide drawing (CAD - Computer Aided Design) or G-code generation from the drawing
(CAM - Computer Automated Manufacturing) functions.
• It can simultaneously move up to 9 axes and supports a variety of interfaces.
• The control can operate true servos (analog or PWM) with the feedback loop closed by the LinuxCNC
software at the computer, or open loop with step-servos or stepper motors.

• Motion control features include: cutter radius and length compensation, path deviation limited to
a specified tolerance, lathe threading, synchronized axis motion, adaptive feedrate, operator feed
override, and constant velocity control.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 2 / 34

• Support for non-Cartesian motion systems is provided via custom kinematics modules. Available
architectures include hexapods (Stewart platforms and similar concepts) and systems with rotary
joints to provide motion such as PUMA or SCARA robots.
• LinuxCNC runs on Linux using real time extensions.

1.2 The Operating System

LinuxCNC is available as ready-to-use packages for the Ubuntu and Debian distributions.

1.3 Getting Help

1.3.1 IRC

IRC stands for Internet Relay Chat. It is a live connection to other LinuxCNC users. The LinuxCNC
IRC channel is #linuxcnc on libera.chat.
The simplest way to get on the IRC is to use the embedded client on this page.

Some IRC etiquette

• Ask specific questions… Avoid questions like ”Can someone help me?”.
• If you’re really new to all this, think a bit about your question before typing it. Make sure you
give enough information so someone can solve your question.
• Have some patience when waiting for an answer, sometimes it takes a while to formulate an
answer or everyone might be busy working or something.
• Set up your IRC account with your unique name so people will know who you are. If you use
the java client, use the same name every time you log in. This helps people remember who you
are and if you have been on before many will remember the past discussions which saves time
on both ends.

Sharing Files
The most common way to share files on the IRC is to upload the file to one of the following or a
similar service and paste the link:

• For text: https://pastebin.com/, http://pastie.org/, https://gist.github.com/

• For pictures: https://imagebin.org/, https://imgur.com/, https://bayimg.com/
• For files: https://filedropper.com/, https://filefactory.com/, https://1fichier.com/

1.3.2 Mailing List

An Internet Mailing List is a way to put questions out for everyone on that list to see and answer at
their convenience. You get better exposure to your questions on a mailing list than on the IRC but
answers take longer. In a nutshell you e-mail a message to the list and either get daily digests or
individual replies back depending on how you set up your account.
You can subscribe to the emc-users mailing list at: https://lists.sourceforge.net/lists/listinfo/emc-users
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 3 / 34

1.3.3 Web Forum

A web forum can be found at https://forum.linuxcnc.org or by following the link at the top of the
linuxcnc.org home page.
This is quite active but the demographic is more user-biased than the mailing list. If you want to be
sure that your message is seen by the developers then the mailing list is to be preferred.

1.3.4 LinuxCNC Wiki

A Wiki site is a user maintained web site that anyone can add to or edit.
The user maintained LinuxCNC Wiki site contains a wealth of information and tips at: https://wiki.linuxcnc.or

1.3.5 Bug Reports

Report bugs to the LinuxCNC github bug tracker.

Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 4 / 34

Chapter 2

System Requirements

2.1 Minimum Requirements

The minimum system to run LinuxCNC and Debian / Ubuntu may vary depending on the exact usage.
Stepper systems in general require faster threads to generate step pulses than servo systems. You
can use the Live CD to test the software before committing to a permanent installation on a computer.
Keep in mind that the Latency Test numbers are more important than the processor speed for software
step generation. More information on the Latency Test is here. In addition LinuxCNC needs to be run
on an operating system that uses a specially modified kernel, see Kernel and Version Requirements.
Additional information is on the LinuxCNC Wiki site: Hardware Requirements
LinuxCNC and Debian Linux should run reasonably well on a computer with the following minimum
hardware specification. These numbers are not the absolute minimum but will give reasonable per-
formance for most stepper systems.

• 700 MHz x86 processor (1.2 GHz x86 processor recommended) or Raspberry Pi 4 or better.
• LinuxCNC 2.8 or later from the Live CD expects a 64-bit capable system.
• 512 MB of RAM, 4 GB with GUI to avoid surprises
• No hard disk for Live CD, 8 GB or more for permanent installation

• Graphics card capable of at least 1024x768 resolution, which is not using the NVidia or ATI fglrx
proprietary drivers. Modern onboard graphic chipsets seem to generally be OK.
• Internet connection (not strictly needed, but very useful for updates and for communicating with
the LinuxCNC community)

Minimum hardware requirements change as Linux distributions evolve so check the Debian web site
for details on the Live CD you’re using. Older hardware may benefit from selecting an older version
of the Live CD when available.
If you plan not to rely on the distribution of readily executable programs (”binaries”) but aim at con-
tributing to the source tree of LinuxCNC, then there is a good chance you want a second computer to
perform the compilation. Even though LinuxCNC and your developments could likely be executed at
the same time with respect to disk space, RAM and even CPU speed, a machine that is busy will have
worse latencies, so you are unlikely to compile your source tree and produce chips at the same time.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 5 / 34

2.2 Kernel and Version requirements

LinuxCNC requires a kernel modified for realtime use to control real machine hardware. It can,
however run on a standard kernel in simulation mode for purposes such as checking G-code, testing
config files and learning the system. To work with these kernel versions there are two versions of
LinuxCNC distributed. The package names are ”linuxcnc” and ”linuxcnc-uspace”.
The realtime kernel options are preempt-rt, RTAI and Xenomai.
You can discover the kernel version of your system with the command:
uname -a

If you see (as above) -rt- in the kernel name then you are running the preempt-rt kernel and should
install the ”uspace” version of LinuxCNC. You should also install uspace for ”sim” configs on non-
realtime kernels
If you see -rtai- in the kernel name then you are running RTAI realtime. See below for the LinuxCNC
version to install.

2.2.1 Preempt-RT with linuxcnc-uspace package

Preempt-RT is the newest of the realtime systems, and is also the version that is closest to a mainline
kernel. Preempt-RT kernels are available as precompiled packages from the main repositories. The
search term ”PREEMPT_RT” will find them, and one can be downloaded and installed just like any
other package. Preempt-RT will generally have the best driver support and is the only option for
systems using the Mesa ethernet-connected hardware driver cards. In general preempt-rt has the
worst latency of the available systems, but there are exceptions.

2.2.2 RTAI with linuxcnc package

RTAI has been the mainstay of LinuxCNC distributions for many years. It will generally give the
best realtime performance in terms of low latency, but might have poorer peripheral support and not
as many screen resolutions. An RTAI kernel is available from the LinuxCNC package repository. If
you installed from the Live/Install image then switching kernel and LinuxCNC flavour is described in
[Installing-RTAI].

2.2.3 Xenomai with linuxcnc-uspace package

Xenomai is also supported, but you will have to find or build the kernel and compile LinuxCNC from
source to utilise it.

2.2.4 RTAI with linuxcnc-uspace package

It is also possible to run LinuxCNC with RTAI in user-space mode. As with Xenomai you will need to
compile from source to do this.

2.3 Problematic Hardware

2.3.1 Laptops

Laptops are not generally suited to real time software step generation. Again a Latency Test run for
an extended time will give you the info you need to determine suitability.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 6 / 34

2.3.2 Video Cards

If your installation pops up with 800 x 600 screen resolution then most likely Debian does not recognize
your video card or monitor. This can sometimes be worked-around by installing drivers or creating /
editing Xorg.conf files.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 7 / 34

Chapter 3

Getting LinuxCNC

This section describes the recommended way to download and make a fresh install of LinuxCNC.
There are also Alternate Install Methods for the adventurous. If you have an existing install that you
want to upgrade, go to the Updating LinuxCNC section instead.

Note
To operate machinery LinuxCNC requires a special kernel with real-time extensions. There are three
possibilities here: preempt-rt, RTAI or Xenomai. In addition there are two versions of LinuxCNC which
work with these kernels. See the table below for details. However for code testing and simulation it
is possible to run the linuxcnc-uspace application on a stock kernel.

Fresh installs of LinuxCNC are most easily created using the Live/Install Image. This is a hybrid ISO
filesystem image that can be written to a USB storage device or a DVD and used to boot a computer. At
boot time you will be given a choice of booting the ”Live” system (to run LinuxCNC without making any
permanent changes to your computer) or booting the Installer (to install LinuxCNC and its operating
system onto your computer’s hard drive).
The outline of the process looks like this:

1. Download the Live/Install Image.

2. Write the image to a USB storage device or DVD.

3. Boot the Live system to test out LinuxCNC.

4. Boot the Installer to install LinuxCNC.

3.1 Download the image

This section describes some methods for downloading the Live/Install image.

3.1.1 Normal Download

Software for LinuxCNC to download is presented on the project’s Downloads page. Most users
will aim for the disk image for Intel/AMD PCs, the URL will resemble https://www.linuxcnc.org/iso/-
linuxcnc_2.9.4-amd64.hybrid.iso.
For the Raspberry Pi, multiple images are provided to address differences between the RPi4 and RPi5.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 8 / 34

Note
Do not use the regular Raspbian distribution for LinuxCNC that may have shipped with your RPi starter
kit - that will not have the real-time kernel and you cannot migrate from Raspbian to Debian’s kernel
image.

3.1.2 Download using zsync

zsync is a download application that efficiently resumes interrupted downloads and efficiently trans-
fers large files with small modifications (if you have an older local copy). Use zsync if you have trouble
downloading the image using the Normal Download method.
zsync in Linux

1. Install zsync using Synaptic or, by running the following in a terminal

sudo apt-get install zsync

2. Then run this command to download the iso to your computer

zsync https://www.linuxcnc.org/iso/linuxcnc_2.9.4-amd64.hybrid.iso

zsync in Windows There is a Windows port of zsync. It works as a console application and can be
downloaded from https://www.assembla.com/spaces/zsync-windows/documents .

3.1.3 Verify the image

(This step is unnecessary if you used zsync)

1. After downloading, verify the checksum of the image to ensure integrity.

md5sum linuxcnc-2.9.4-amd64.iso

or
sha256sum linuxcnc-2.9.4-amd64.iso

1. Then compare to these checksums

amd64 (PC)
md5sum: 1815aceaac0e7861747aa34d61846e79
sha256sum: 08b3f59233e47c91cf1c9a85c41df48542c97b134efefa7446d3060c9a3e644b
arm64 (Pi)
md5sum: 4547e8a72433efb033f0a5cf166a5cd2
sha256sum: ff3ba9b8dfb93baf1e2232746655f8521a606bc0fab91bffc04ba74cc3be6bf0

Verify md5sum on Windows or Mac Windows and Mac OS X do not come with an md5sum program,
but there are alternatives. More information can be found at: How To MD5SUM

3.2 Write the image to a bootable device

The LinuxCNC Live/Install ISO Image is a hybrid ISO image which can be written directly to a USB
storage device (flash drive) or a DVD and used to boot a computer. The image is too large to fit on a
CD.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 9 / 34

3.2.1 Raspberry Pi Image

The Raspbery Pi image is a completes SD card image and should be written to an SD card with the
[Raspberry Pi Imager App](https://www.raspberrypi.com/software/).

3.2.2 AMD-64 (x86-64, PC) Image using GUI tools

Download and install [Balena Etcher](https://etcher.balena.io/#download-etcher) (Linux, Windows,

Mac) and write the downloaded image to a USB drive.
If your image fails to boot then please also try Rufus. It looks more complicated but seems to be more
compatible with various BIOSes.

3.2.3 Command line - Linux

1. Connect a USB storage device (for example a flash drive or thumb drive type device).
2. Determine the device file corresponding to the USB flash drive. This information can be found
in the output of dmesg after connecting the device. /proc/partitions may also be helpful.
3. Use the dd command to write the image to your USB storage device. For example, if your storage
device showed up as /dev/sde, then use this command:
dd if=linuxcnc_2.9.4-amd64.hybrid.iso of=/dev/sde

3.2.4 Command line - MacOS

1. Open a terminal and type

diskutil list

2. Insert the USB and note the name of the new disk that appears, eg /dev/disk5
3. unmount the USB. The number found above should be substitued in place of the N
diskutil unmountDisk /dev/diskN

4. Transfer the data with dd, as for Linux above. Note that the disk name has an added ”r” at the
begining
sudo dd if=/linuxcnc_2.9.4-amd64.hybrid.iso of=/dev/rdiskN bs=1m

5. Note that this may take a long time to complete and there will be no feedback during the process.

Writing the image to a DVD in Linux

1. Insert a blank DVD into your burner. A CD/DVD Creator or Choose Disc Type window will pop
up. Close this, as we will not be using it.
2. Browse to the downloaded image in the file browser.
3. Right click on the ISO image file and choose Write to Disc.
4. Select the write speed. It is recommended that you write at the lowest possible speed.
5. Start the burning process.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 10 / 34

6. If a choose a file name for the disc image window pops up, just pick OK.

Writing the image to a DVD in Windows

1. Download and install Infra Recorder, a free and open source image burning program: http://infrarecorde

2. Insert a blank CD in the drive and select Do nothing or Cancel if an auto-run dialog pops up.
3. Open Infra Recorder, and select the Actions menu, then Burn image.

Writing the image to a DVD in Mac OSX

1. Download the .iso file

2. Right-click on the file in the Finder window and select ”Burn to disc” (The option to burn to disc
will only appear if the machine has an optical drive fitted or connected)

3.3 Testing LinuxCNC

With the USB storage device plugged in or the DVD in the DVD drive, shut down the computer then
turn the computer back on. This will boot the computer from the Live/Install Image and choose the
Live boot option.

Note
If the system does not boot from the DVD or USB stick, it may be necessary to change the boot order
in the PC BIOS.

Once the computer has booted up you can try out LinuxCNC without installing it. You can not create
custom configurations or modify most system settings in a Live session, but you can (and should) run
the latency test.
To try out LinuxCNC: from the Applications/CNC menu pick LinuxCNC. A dialog box will open from
which you can choose one of many sample configurations. At this point it only really makes sense
to pick a ”sim” configuration. Some of the sample configurations include onscreen 3D simulated
machines, look for ”Vismach” to see these.
To see if your computer is suitable for software step pulse generation run the Latency Test as shown
here.
At the time of writing the Live Image is only available with the preempt-rt kernel and a matching
LinuxCNC. On some hardware this might not offer good enough latency. There is an experimental
version available using the RTAI realtime kernel which will often give better latency.

3.4 Installing LinuxCNC

To install LinuxCNC from the Live CD select Install (Graphical) at bootup.

Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 11 / 34

3.5 Updates to LinuxCNC

With the normal install the Update Manager will notify you of updates to LinuxCNC when you go on
line and allow you to easily upgrade with no Linux knowledge needed. It is OK to upgrade everything
except the operating system when asked to.

Warning
Do not upgrade the operating system if prompted to do so. You should accept OS updates
however, especially security updates.

3.6 Install Problems

In rare cases you might have to reset the BIOS to default settings if during the Live CD install it cannot
recognize the hard drive during the boot up.

3.7 Alternate Install Methods

The easiest, preferred way to install LinuxCNC is to use the Live/Install Image as described above.
That method is as simple and reliable as we can make it, and is suitable for novice users and experi-
enced users alike. However, this will typically replace any existing operating system. If you have files
on the target PC that you want to keep, then use one of the methods described in this section.
In addition, for experienced users who are familiar with Debian system administration (finding install
images, manipulating apt sources, changing kernel flavors, etc), new installs are supported on fol-
lowing platforms: (”amd64” means ”64-bit”, and is not specific to AMD processors, it will run on any
64-bit x86 system)

Distribution Architecture Kernel Package name Typical use

Debian amd64 & arm64 preempt-rt linuxcnc-uspace machine control
Bookworm & simulation
Debian amd64 RTAI linuxcnc machine control
Bookworm
Debian Bullseye amd64 preempt-rt linuxcnc-uspace machine control
& simulation
Debian Buster amd64 & arm64 preempt-rt linuxcnc-uspace machine control
& simulation
Debian Buster amd64 RTAI linuxcnc machine control
Any Any Stock linuxcnc-uspace simulation ONLY

Note
LinuxCNC v2.9 is not supported on Debian 9 or older.

Preempt-RT kernels The Preempt-rt kernels are available for Debian from the regular debian.org
archive. The package is called linux-image-rt-*. Simply install the package in the same way as any
other package from the Synaptic Package manager or with apt-get at the command-line.
RTAI Kernels The RTAI kernels are available for download from the linuxcnc.org debian archive. The
apt source is:
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 12 / 34

• Debian Bookworm: deb http://linuxcnc.org bookworm base

• Debian Bullseye: deb http://linuxcnc.org bullseye base
• Debian Buster: deb http://linuxcnc.org buster base

LinuxCNC and the RTAI kernel are now only available for 64-bit OSes but there are very few surviving
systems that can not run a 64-bit OS.

3.7.1 Installing on Debian Bookworm (with Preempt-RT kernel)

1. Install Debian Bookworm (Debian 12), amd64 version. You can download the installer here:
https://www.debian.org/distrib/
2. After burning the iso and booting up if you don’t want Gnome desktop select Advanced Options
> Alternative desktop environments and pick the one you like. Then select Install or Graphical
Install.

Warning
Do not enter a root password, if you do sudo is disabled and you won’t be able to complete
the following steps.

3. Run the following in a terminal to bring the machine up to date with the latest packages.
sudo apt-get update
sudo apt-get dist-upgrade

Note
It is possible to download a version of LinuxCNC directly from Debian but this will install an old pre-
release version, and is not recommended at this time.

1. Install the Preempt-RT kernel and modules

sudo apt-get install linux-image-rt-amd64

2. Re-boot, and select the Linux 6.1.0-10-rt-amd64 kernel. The exact kernel version might be dif-
ferent, look for the ”-rt” suffix. This might be hidden in the ”Advanced options for Debian Book-
worm” sub-menu in Grub. When you log in, verify that ̀PREEMPT RT ̀is reported by the following
command.
uname -v

3. Open Applications Menu > System > Synaptic Package Manager search for linux-image and right
click on the original non-rt and select Mark for Complete Removal. Reboot. This is to force the
system to boot from the RT kernel. If you prefer to retain both kernels then the other kernels
need not be deleted, but grub boot configuration changes will be needed beyond the scope of
this document.
4. Add the LinuxCNC Archive Signing Key to your apt keyring by downloading [the LinuxCNC in-
staller script](https://www.linuxcnc.org/linuxcnc-install.sh) You will need to make the script exe-
cutable to run it:

chmod +x linuxcnc-install.sh

Then you can run the installer:

sudo ./linuxcnc-install.sh
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 13 / 34

3.7.2 Installing on Debian Bookworm (with experimental RTAI kernel)

1. This kernel and LinuxCNC version can be installed on top of the Live DVD install, or alternatively
on a fresh Install of Debian Bookworm 64-bit as described above.
2. You can add the LinuxCNC Archive signing key and repository information by downloading and
running the installer script as decribed above. If an RTAI kernel is detected it will stop before
installing any packages.
3. Update the package list from linuxcnc.org
sudo apt-get update

4. Install the new realtime kernel, RTAI and the rtai version of linuxcnc.
sudo apt-get install linuxcnc

Reboot the machine, ensuring that the system boots from the new 5.4.258-rtai kernel.

3.7.3 Installing on Raspbian 12

Don’t do that. The latencies are too bad with the default kernel and the PREEMPT_RT (the RT is
important) kernel of Debian does not boot on the Pi (as of 1/2024). Please refer to the images provided
online. You can create them yourself following the scripts provided online.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 14 / 34

Chapter 4

Running LinuxCNC

4.1 Invoking LinuxCNC

After installation, LinuxCNC starts just like any other Linux program: run it from the terminal by
issuing the command linuxcnc, or select it in the Applications -> CNC menu.

4.2 Configuration Launcher

When starting LinuxCNC (from the CNC menu or from the command line without specifying an INI
file) the Configuration Selector dialog starts.
The Configuration Selector dialog allows the user to pick one of their existing configurations (My
Configurations) or select a new one (from the Sample Configurations) to be copied to their home
directory. Copied configurations will appear under My Configurations on the next invocation of the
Configuration Selector.
The Configuration Selector offers a selection of configurations organized:

• My Configurations - User configurations located in linuxcnc/configs in your home directory.

• Sample Configurations - Sample configurations, when selected, are copied to linuxcnc/configs. Once
a sample configuration was copied to your local directory, the launcher will offer it as My Configu-
rations. The names under which these local configurations are presented correspond to the names
of the directories within the configs/ directory:

– sim - Configurations that include simulated hardware. These can be used for testing or learning
how LinuxCNC works.
– by_interface - Configurations organized by GUI.
– by_machine - Configurations organized by machine.
– apps - Applications that do not require starting linuxcnc but may be useful for testing or trying
applications like PyVCP or GladeVCP.
– attic - Obsolete or historical configurations.

The sim configurations are often the most useful starting point for new users and are organized around
supported GUIs:

• axis - Keyboard and Mouse GUI

• craftsman - Touch Screen GUI (no longer maintained ???)
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 15 / 34

• gmoccapy - Touch Screen GUI

• gscreen - Touch Screen GUI
• pyvcp_demo - Python Virtual Control Panel
• qtaxis - Touch Screen GUI, axis lookalike
• qtdragon - Touch Screen GUI
• qtdragon_hd - Touch Screen GUI, high definition
• qtplasmac - Touch Screen GUI, for plasma tables
• qttouchy - Touch Screen GUI
• tklinuxcnc - Keyboard and Mouse GUI (no longer maintained)
• touchy - Touch Screen GUI
• woodpecker - Touch Screen GUI A GUI configuration directory may contain subdirectories with
configurations that illustrate special situations or the embedding of other applications.

The by_interface configurations are organized around common, supported interfaces like:

• general mechatronics
• mesa
• parport
• pico
• pluto
• servotogo
• vigilant
• vitalsystems

Related hardware may be required to use these configurations as starting points for a system.
The by_machine configurations are organized around complete, known systems like:

• boss
• cooltool
• scortbot erIII
• sherline
• smithy
• tormach

A complete system may be required to use these configurations.

The apps items are typically either:

1. utilities that don’t require starting linuxcnc

2. demonstrations of applications that can be used with linuxcnc

• info - creates a file with system information that may be useful for problem diagnosis.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 16 / 34

• gladevcp - Example GladeVCP applications.

• halrun - Starts halrun in an terminal.
• latency - Applications to investigate latency
– latency-histogram-1 - histogram for single servo thread
– latency-histogram - histogram
– latency-test - standard test
– latency-plot - stripchart
• parport - Applications to test parport.
• pyvcp - Example pyvcp applications.
• xhc-hb04 - Applications to test an xhc-hb04 USB wireless MPG

Note
Under the Apps directory, only applications that are usefully modified by the user are offered for
copying to the user’s directory.

Figure 4.1: LinuxCNC Configuration Selector

Click any of the listed configurations to display specific information about it. Double-click a configu-
ration or click OK to start the configuration.
Select Create Desktop Shortcut and then click OK to add an icon on the Ubuntu desktop to directly
launch this configuration without showing the Configuration Selector screen.
When you select a configuration from the Sample Configurations section, it will automatically place a
copy of that config in the ~/linuxcnc/configs directory.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 17 / 34

4.3 Next steps in configuration

After finding the sample configuration that uses the same interface hardware as your machine (or a
simulator configuration), and saving a copy to your home directory, you can customize it according to
the details of your machine. Refer to the Integrator Manual for topics on configuration.

4.4 Simulator Configurations

All configurations listed under Sample Configurations/sim are intended to run on any computer. No
specific hardware is required and real-time support is not needed.
These configurations are useful for studying individual capabilities or options. The sim configurations
are organized according to the graphical user interface used in the demonstration. The directory for
axis contains the most choices and subdirectories because it is the most tested GUI. The capabilities
demonstrated with any specific GUI may be available in other GUIs as well.

4.5 Configuration Resources

The Configuration Selector copies all files needed for a configuration to a new subdirectory of ~/lin-
uxcnc/configs (equivalently: /home/username/linuxcnc/configs). Each created directory will include
at least one INI file (iniflename.ini) that is used to describe a specific configuration.
File resources within the copied directory will typically include one or more INI file (filename.ini)
for related configurations and a tool table file (toolfilename.tbl). Additionally, resources may include
HAL files (filename.hal, filename.tcl), a README file for describing the directory, and configuration
specific information in a text file named after a specific configuration (inifilename.txt). That latter two
files are displayed when using the Configuration Selector.
The supplied sample configurations may specify the parameter HALFILE (filename.hal) in the config-
uration INI file that are not present in the copied directory because they are found in the system HAL
file library. These files can be copied to the user configuration directory and altered as required by
the user for modification or test. Since the user configuration directory is searched first when finding
HAL files, local modifications will then prevail.
The Configuration selector makes a symbolic link in the user configuration directory (named hallib)
that points to the system HAL file library. This link simplifies copying a library file. For example, to
copy the library core_sim.hal file in order to make local modifications:
cd ~/linuxcnc/configs/name_of_configuration
cp hallib/core_sim.hal core_sim.hal
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 18 / 34

Chapter 5

Updating LinuxCNC

Updating LinuxCNC to a new minor release (ie to a new version in the same stable series, for example
from 2.9.1 to 2.9.2) is an automatic process if your PC is connected to the internet. You will see an
update prompt after a minor release along with other software updates. If you don’t have an internet
connection to your PC see Updating without Network.

5.1 Upgrade to the new version

This section describes how to upgrade LinuxCNC from version 2.8.x to a 2.9.y version. It assumes
that you have an existing 2.8 install that you want to update.
To upgrade LinuxCNC from a version older than 2.8, you have to first upgrade your old install to 2.8,
then follow these instructions to upgrade to the new version.
If you do not have an old version of LinuxCNC to upgrade, then you’re best off making a fresh install
of the new version as described in the section Getting LinuxCNC.
Furthermore, if you are running Ubuntu Precise or Debian Wheezy it is well worth considering making
a backup of the ”linuxcnc” directory on removable media and performing a clean install of a newer OS
and LinuxCNC version as these releases were EOL in 2017 and 2018 respectively. If you are running
on Ubuntu Lucid then you will have to do this, as Lucid is no longer supported by LinuxCNC (it was
EOL in 2013).
To upgrade major versions like 2.8 to 2.9 when you have a network connection at the machine you need
to disable the old linuxcnc.org apt sources in the file /etc/apt/sources.list and add a new linuxcnc.org
apt source for 2.9, then upgrade LinuxCNC.
The details will depend on which platform you’re running on. Open a terminal then type lsb_release
-ic to find this information out:
lsb_release -ic
Distributor ID: Debian
Codename: Buster

You should be running on Debian Buster, Bullseye or Bookworm or Ubuntu 20.04 ”Focal Fossa” or
newer. LinuxCNC 2.9.y will not run on older distributions than these.
You will also need to check which realtime kernel is being used:
uname -r
6.1.0-10-rt-amd64
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 19 / 34

If you see (as above) -rt- in the kernel name then you are running the preempt-rt kernel and should
install the ”uspace” version of LinuxCNC. You should also install uspace for ”sim” configs on non-
realtime kernels
If you see -rtai- in the kernel name then you are running RTAI realtime. See below for the LinuxCNC
version to install. RTAI packages are available for Bookworm and Buster but not currently for Bullseye.

5.1.1 Apt Sources Configuration

• Open the Software Sources window. The process for doing this differs slightly on the three sup-
ported platforms:

– Debian:
∗ Click on Applications Menu, then System, then Synaptic Package Manager.
∗ In Synaptic, click on the Settings menu, then click Repositories to open the Software Sources
window.
– Ubuntu Precise:
∗ Click on the Dash Home icon in the top left.
∗ In the Search field, type ”software”, then click on the Ubuntu Software Center icon.
∗ In the Ubuntu Software Center window, click on the Edit menu, then click on Software Sources...
to open the Software Sources window.
– Ubuntu Lucid:
∗ Click the System menu, then Administration, then Synaptic Package Manager.
∗ In Synaptic, click on the Settings menu, then click on Repositories to open the Software
Sources window.

• In the Software Sources window, select the Other Software tab.

• Delete or un-check all the old linuxcnc.org entries (leave all non-linuxcnc.org lines as they are).
• Click the Add button and add a new apt line. The line will be slightly different on the different
platforms:

Table 5.1: Tabular overview on variants of the Operating

System and the corresponding configuration of the repos-
itory. The configuration can be performed in the GUI of
the package manager or in the file /etc/apt/sources.list.

OS / Realtime Version Repository

Debian Buster - preempt deb https://linuxcnc.org buster base 2.9-uspace
Debian Buster - RTAI deb https://linuxcnc.org buster base 2.9-rt
Debian Bullseye - preempt deb https://linuxcnc.org bullseye base 2.9-uspace
Debian Bookworm - preempt deb https://linuxcnc.org bookworm base 2.9-uspace
Debian Bookworm - RTAI deb https://linuxcnc.org bookworm base 2.9-rt
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 20 / 34

Figure 5.1: Figure with a screenshot of the repository configuration of the synaptic package manager.

• Click Add Source, then Close in the Software Sources window. If it pops up a window informing
you that the information about available software is out-of-date, click the Reload button.

5.1.2 Upgrading to the new version

Now your computer knows where to get the new version of the software, next we need to install it.
The process again differs depending on your platform.

5.1.2.1 Debian Buster, Bullseye and Bookworm

Debian uses the Synaptic Package Manager.

Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 21 / 34

• Open Synaptic using the instructions in Setting apt sources above.

• Click the Reload button.
• Use the Search function to search for linuxcnc.
• The package is called ”linuxcnc” for RTAI kernels and ”linuxcnc-uspace” for preempt-rt.
• Click the check box to mark the new linuxcnc and linuxcnc-doc-* packages for upgrade. The package
manager may select a number of additional packages to be installed, to satisfy dependencies that
the new linuxcnc package has.
• Click the Apply button, and let your computer install the new package. The old linuxcnc package
will be automatically upgraded to the new one.

5.1.3 Ubuntu

• Click on the Dash Home icon in the top left.

• In the Search field, type ”update”, then click on the Update Manager icon.
• Click the Check button to fetch the list of packages available.
• Click the Install Updates button to install the new versions of all packages.

5.2 Updating without Network

To update without a network connection you need to download the .deb then install it with dpkg. The
.debs can be found in https://linuxcnc.org/dists/ .
You have to drill down from the above link to find the correct deb for your installation. Open a terminal
and type in lsb_release -ic to find the release name of your OS.
> lsb_release -ic
Distributor ID: Debian
Codename: bullseye

Pick the OS from the list then pick the major version you want like 2.9-rt for RTAI or 2.9-rtpreempt or
2.9-uspace for preempt-rt.
Next pick the type of computer you have: binary-amd64 for any 64-bit x86, binary-i386 for 32 bit,
binary-armhf (32bit) or binary-arm64 (64bit) for Raspberry Pi.
Next pick the version you want from the bottom of the list like linuxcnc-uspace_2.8.0_amd64.deb
(choose the latest by date). Download the deb and copy it to your home directory. You can rename
the file to something a bit shorter with the file manager like linuxcnc_2.9.2.deb then open a terminal
and install it with the package manager with this command:
sudo dpkg -i linuxcnc_2.9.2.deb

5.3 Updating Configuration Files for 2.9

5.3.1 Stricter handling of pluggable interpreters

If you just run regular G-code and you don’t know what a pluggable interpreter is, then this section
does not affect you.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 22 / 34

A seldom-used feature of LinuxCNC is support for pluggable interpreters, controlled by the undocu-
mented [TASK]INTERPRETER INI setting.
Versions of LinuxCNC before 2.9.0 used to handle an incorrect [TASK]INTERPRETER setting by auto-
matically falling back to using the default G-code interpreter.
Since 2.9.0, an incorrect [TASK]INTERPRETER value will cause LinuxCNC to refuse to start up. Fix this
condition by deleting the [TASK]INTERPRETER setting from your INI file, so that LinuxCNC will use
the default G-code interpreter.

5.3.2 Canterp

If you just run regular G-code and you don’t use the canterp pluggable interpreter, then this section
does not affect you.
In the extremely unlikely event that you are using canterp, know that the module has moved from
/usr/lib/libcanterp.so to /usr/lib/linuxcnc/canterp.so, and the [TASK]INTERPRETER setting
correspondingly needs to change from libcanterp.so to canterp.so.

5.4 Updating Configuration Files (for 2.9.y)

No changes should be necessary to configuration files when moving from 2.8.x to 2.9.y.

5.4.1 Spindle limits in the INI

It is now possible to add settings to the [SPINDLE] section of the INI file
MAX_FORWARD_VELOCITY = 20000 The maximum spindle speed (in rpm)
MIN_FORWARD_VELOCITY = 3000 The minimum spindle speed (in rpm)
MAX_REVERSE_VELOCITY = 20000 This setting will default to MAX_FORWARD_VELOCITY if omit-
ted.
MIN_REVERSE_VELOCITY = 3000 ̀ This setting is equivalent to MIN_FORWARD_VELOCITY but for
reverse spindle rotation. It will default to the MIN_FORWARD_VELOCITY if omitted.
INCREMENT = 200 Sets the step size for spindle speed increment / decrement commands. This can
have a different value for each spindle. This setting is effective with AXIS and Touchy but note that
some control screens may handle things differently.
HOME_SEARCH_VELOCITY = 100 - Accepted but currently does nothing
HOME_SEQUENCE = 0 - Accepted but currently does nothing

5.5 New HAL components

5.5.1 Non-Realtime

mdro mqtt-publisher pi500_vfd pmx485-test qtplasmac-cfg2prefs qtplasmac-materials qtplasmac-plasmac2q

qtplasmac-setup sim-torch svd-ps_vfd

5.5.2 Realtime

anglejog div2 enum filter_kalman flipflop hal_parport homecomp limit_axis mesa_uart millturn scaled_s32_su
tof ton
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 23 / 34

5.6 New Drivers

A framework for controlling ModBus devices using the serial ports on many Mesa cards has been
introduced. http://linuxcnc.org/docs/2.9/html/drivers/mesa_modbus.html
A new GPIO driver for any GPIO which is supported by the gpiod library is now included: http://linuxcnc.org/-
docs/2.9/html/drivers/hal_gpio.html
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 24 / 34

Chapter 6

Glossary

A listing of terms and what they mean. Some terms have a general meaning and several additional
meanings for users, installers, and developers.

Acme Screw
A type of lead-screw that uses an Acme thread form. Acme threads have somewhat lower friction
and wear than simple triangular threads, but ball-screws are lower yet. Most manual machine
tools use acme lead-screws.
Axis
One of the computer controlled movable parts of the machine. For a typical vertical mill, the
table is the X axis, the saddle is the Y axis, and the quill or knee is the Z axis. Angular axes like
rotary tables are referred to as A, B, and C. Additional linear axes relative to the tool are called
U, V, and W respectively.
AXIS(GUI)
One of the Graphical User Interfaces available to users of LinuxCNC. It features the modern use
of menus and mouse buttons while automating and hiding some of the more traditional LinuxCNC
controls. It is the only open-source interface that displays the entire tool path as soon as a file is
opened.
GMOCCAPY (GUI)
A Graphical User Interfaces available to users of LinuxCNC. It features the use and feel of an
industrial control and can be used with touch screen, mouse and keyboard. It support embedded
tabs and hal driven user messages, it offers a lot of hal beens to be controlled with hardware.
GMOCCAPY is highly customizable.
Backlash
The amount of ”play” or lost motion that occurs when direction is reversed in a lead screw. or
other mechanical motion driving system. It can result from nuts that are loose on leadscrews,
slippage in belts, cable slack, ”wind-up” in rotary couplings, and other places where the mechan-
ical system is not ”tight”. Backlash will result in inaccurate motion, or in the case of motion
caused by external forces (think cutting tool pulling on the work piece) the result can be broken
cutting tools. This can happen because of the sudden increase in chip load on the cutter as the
work piece is pulled across the backlash distance by the cutting tool.

Backlash Compensation
Any technique that attempts to reduce the effect of backlash without actually removing it from
the mechanical system. This is typically done in software in the controller. This can correct the
final resting place of the part in motion but fails to solve problems related to direction changes
while in motion (think circular interpolation) and motion that is caused when external forces
(think cutting tool pulling on the work piece) are the source of the motion.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 25 / 34

Ball Screw
A type of lead-screw that uses small hardened steel balls between the nut and screw to reduce
friction. Ball-screws have very low friction and backlash, but are usually quite expensive.
Ball Nut
A special nut designed for use with a ball-screw. It contains an internal passage to re-circulate
the balls from one end of the screw to the other.
CNC
Computer Numerical Control. The general term used to refer to computer control of machinery.
Instead of a human operator turning cranks to move a cutting tool, CNC uses a computer and
motors to move the tool, based on a part program.

Comp
A tool used to build, compile and install LinuxCNC HAL components.
Configuration(n)
A directory containing a set of configuration files. Custom configurations are normally saved in
the users home/linuxcnc/configs directory. These files include LinuxCNC’s traditional INI file and
HAL files. A configuration may also contain several general files that describe tools, parameters,
and NML connections.
Configuration(v)
The task of setting up LinuxCNC so that it matches the hardware on a machine tool.
Coordinate Measuring Machine
A Coordinate Measuring Machine is used to make many accurate measurements on parts. These
machines can be used to create CAD data for parts where no drawings can be found, when a hand-
made prototype needs to be digitized for moldmaking, or to check the accuracy of machined or
molded parts.
Display units
The linear and angular units used for onscreen display.
DRO
A Digital Read Out is a system of position-measuring devices attached to the slides of a machine
tool, which are connected to a numeric display showing the current location of the tool with
respect to some reference position. DROs are very popular on hand-operated machine tools
because they measure the true tool position without backlash, even if the machine has very loose
Acme screws. Some DROs use linear quadrature encoders to pick up position information from
the machine, and some use methods similar to a resolver which keeps rolling over.
EDM
EDM is a method of removing metal in hard or difficult to machine or tough metals, or where
rotating tools would not be able to produce the desired shape in a cost-effective manner. An
excellent example is rectangular punch dies, where sharp internal corners are desired. Milling
operations can not give sharp internal corners with finite diameter tools. A wire EDM machine
can make internal corners with a radius only slightly larger than the wire’s radius. A sinker EDM
can make internal corners with a radius only slightly larger than the radius on the corner of the
sinking electrode.

EMC
The Enhanced Machine Controller. Initially a NIST project. Renamed to LinuxCNC in 2012.
EMCIO
The module within LinuxCNC that handles general purpose I/O, unrelated to the actual motion
of the axes.

EMCMOT
The module within LinuxCNC that handles the actual motion of the cutting tool. It runs as a
real-time program and directly controls the motors.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 26 / 34

Encoder
A device to measure position. Usually a mechanical-optical device, which outputs a quadrature
signal. The signal can be counted by special hardware, or directly by the parport with LinuxCNC.
Feed
Relatively slow, controlled motion of the tool used when making a cut.
Feed rate
The speed at which a cutting motion occurs. In auto or MDI mode, feed rate is commanded using
an F word. F10 would mean ten machine units per minute.
Feedback
A method (e.g., quadrature encoder signals) by which LinuxCNC receives information about the
position of motors.
Feedrate Override
A manual, operator controlled change in the rate at which the tool moves while cutting. Often
used to allow the operator to adjust for tools that are a little dull, or anything else that requires
the feed rate to be ”tweaked”.
Floating Point Number
A number that has a decimal point. (12.300) In HAL it is known as float.
G-code
The generic term used to refer to the most common part programming language. There are
several dialects of G-code, LinuxCNC uses RS274/NGC.
GUI
Graphical User Interface.

General
A type of interface that allows communications between a computer and a human (in most
cases) via the manipulation of icons and other elements (widgets) on a computer screen.
LinuxCNC
An application that presents a graphical screen to the machine operator allowing manipula-
tion of the machine and the corresponding controlling program.
HAL
Hardware Abstraction Layer. At the highest level, it is simply a way to allow a number of building
blocks to be loaded and interconnected to assemble a complex system. Many of the building
blocks are drivers for hardware devices. However, HAL can do more than just configure hardware
drivers.
Home
A specific location in the machine’s work envelope that is used to make sure the computer and
the actual machine both agree on the tool position.
INI file
A text file that contains most of the information that configures LinuxCNC for a particular ma-
chine.
Instance
One can have an instance of a class or a particular object. The instance is the actual object
created at runtime. In programmer jargon, the ”Lassie” object is an instance of the ”Dog” class.
Joint Coordinates
These specify the angles between the individual joints of the machine. See also Kinematics
Jog
Manually moving an axis of a machine. Jogging either moves the axis a fixed amount for each
key-press, or moves the axis at a constant speed as long as you hold down the key. In manual
mode, jog speed can be set from the graphical interface.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 27 / 34

kernel-space
Code running inside the kernel, as opposed to code running in userspace. Some realtime sys-
tems (like RTAI) run realtime code in the kernel and non-realtime code in userspace, while other
realtime systems (like Preempt-RT) run both realtime and non-realtime code in userspace.
Kinematics
The position relationship between world coordinates and joint coordinates of a machine. There
are two types of kinematics. Forward kinematics is used to calculate world coordinates from joint
coordinates. Inverse kinematics is used for exactly the opposite purpose. Note that kinematics
does not take into account, the forces, moments etc. on the machine. It is for positioning only.
Lead-screw
An screw that is rotated by a motor to move a table or other part of a machine. Lead-screws are
usually either ball-screws or acme screws, although conventional triangular threaded screws
may be used where accuracy and long life are not as important as low cost.
Machine units
The linear and angular units used for machine configuration. These units are specified and used
in the INI file. HAL pins and parameters are also generally in machine units.

MDI
Manual Data Input. This is a mode of operation where the controller executes single lines of
G-code as they are typed by the operator.
NIST
National Institute of Standards and Technology. An agency of the Department of Commerce in
the United States.
NML
Neutral Message Language provides a mechanism for handling multiple types of messages in
the same buffer as well as simplifying the interface for encoding and decoding buffers in neutral
format and the configuration mechanism.

Offsets
An arbitrary amount, added to the value of something to make it equal to some desired value.
For example, G-code programs are often written around some convenient point, such as X0, Y0.
Fixture offsets can be used to shift the actual execution point of that G-code program to properly
fit the true location of the vice and jaws. Tool offsets can be used to shift the ”uncorrected” length
of a tool to equal that tool’s actual length.
Part Program
A description of a part, in a language that the controller can understand. For LinuxCNC, that
language is RS-274/NGC, commonly known as G-code.
Program Units
The linear and angular units used in a part program. The linear program units do not have to
be the same as the linear machine units. See G20 and G21 for more information. The angular
program units are always measured in degrees.
Python
General-purpose, very high-level programming language. Used in LinuxCNC for the Axis GUI,
the StepConf configuration tool, and several G-code programming scripts.
Rapid
Fast, possibly less precise motion of the tool, commonly used to move between cuts. If the tool
meets the workpiece or the fixturing during a rapid, it is probably a bad thing!
Rapid rate
The speed at which a rapid motion occurs. In auto or MDI mode, rapid rate is usually the max-
imum speed of the machine. It is often desirable to limit the rapid rate when testing a G-code
program for the first time.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 28 / 34

Real-time
Software that is intended to meet very strict timing deadlines. On Linux, in order to meet these
requirements it is necessary to install a realtime kernel such as RTAI or Preempt-RT, and build
the LinuxCNC software to run in the special real-time environment. Realtime software can run
in the kernel or in userspace, depending on the facilities offered by the system.
RTAI
Real Time Application Interface, see https://www.rtai.org/, the real-time extensions for Linux that
LinuxCNC can use to achieve real-time performance.
RTLINUX
See https://en.wikipedia.org/wiki/RTLinux, an older real-time extension for Linux that LinuxCNC
used to use to achieve real-time performance. Obsolete, replaced by RTAI.
RTAPI
A portable interface to real-time operating systems including RTAI and POSIX pthreads with
realtime extensions.
RS-274/NGC
The formal name for the language used by LinuxCNC part programs.
Servo Motor
Generally, any motor that is used with error-sensing feedback to correct the position of an actu-
ator. Also, a motor which is specially-designed to provide improved performance in such appli-
cations.
Servo Loop
A control loop used to control position or velocity of an motor equipped with a feedback device.
Signed Integer
A whole number that can have a positive or negative sign. In HAL it is known as s32. (A signed
32-bit integer has a usable range of -2,147,483,647 to +2,147,483,647.)
Spindle
The part of a machine tool that spins to do the cutting. On a mill or drill, the spindle holds the
cutting tool. On a lathe, the spindle holds the workpiece.
Spindle Speed Override
A manual, operator controlled change in the rate at which the tool rotates while cutting. Often
used to allow the operator to adjust for chatter caused by the cutter’s teeth. Spindle Speed
Override assumes that the LinuxCNC software has been configured to control spindle speed.
StepConf
An LinuxCNC configuration wizard. It is able to handle many step-and-direction motion command
based machines. It writes a full configuration after the user answers a few questions about the
computer and machine that LinuxCNC is to run on.
Stepper Motor
A type of motor that turns in fixed steps. By counting steps, it is possible to determine how far
the motor has turned. If the load exceeds the torque capability of the motor, it will skip one or
more steps, causing position errors.
TASK
The module within LinuxCNC that coordinates the overall execution and interprets the part pro-
gram.
Tcl/Tk
A scripting language and graphical widget toolkit with which several of LinuxCNCs GUIs and
selection wizards were written.
Traverse Move
A move in a straight line from the start point to the end point.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 29 / 34

Units
See ”Machine Units”, ”Display Units”, or ”Program Units”.
Unsigned Integer
A whole number that has no sign. In HAL it is known as u32. (An unsigned 32-bit integer has a
usable range of zero to 4,294,967,296.)

World Coordinates
This is the absolute frame of reference. It gives coordinates in terms of a fixed reference frame
that is attached to some point (generally the base) of the machine tool.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 30 / 34

Chapter 7

Legal Section

Translations of this file provided in the source tree are not legally binding.

7.1 Copyright Terms

Copyright (c) 2000-2022 LinuxCNC.org

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free
Documentation License, Version 1.1 or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is
included in the section entitled ”GNU Free Documentation License”.

7.2 GNU Free Documentation License

GNU Free Documentation License Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-
1301 USA. Everyone is permitted to copy and distribute verbatim copies of this license document, but
changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other written document ”free” in the
sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not being considered responsible for
modifications made by others.
This License is a kind of ”copyleft”, which means that derivative works of the document must them-
selves be free in the same sense. It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software
needs free documentation: a free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to software manuals; it can be used for any
textual work, regardless of subject matter or whether it is published as a printed book. We recommend
this License principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 31 / 34

This License applies to any manual or other work that contains a notice placed by the copyright holder
saying it can be distributed under the terms of this License. The ”Document”, below, refers to any
such manual or work. Any member of the public is a licensee, and is addressed as ”you”.
A ”Modified Version” of the Document means any work containing the Document or a portion of it,
either copied verbatim, or with modifications and/or translated into another language.
A ”Secondary Section” is a named appendix or a front-matter section of the Document that deals
exclusively with the relationship of the publishers or authors of the Document to the Document’s
overall subject (or to related matters) and contains nothing that could fall directly within that overall
subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section
may not explain any mathematics.) The relationship could be a matter of historical connection with
the subject or with related matters, or of legal, commercial, philosophical, ethical or political position
regarding them.
The ”Invariant Sections” are certain Secondary Sections whose titles are designated, as being those
of Invariant Sections, in the notice that says that the Document is released under this License.
The ”Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover
Texts, in the notice that says that the Document is released under this License.
A ”Transparent” copy of the Document means a machine-readable copy, represented in a format whose
specification is available to the general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of pixels) generic paint programs
or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters
or for automatic translation to a variety of formats suitable for input to text formatters. A copy made
in an otherwise Transparent file format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is not ”Transparent” is called
”Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input
format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming
simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary
formats that can be read and edited only by proprietary word processors, SGML or XML for which the
DTD and/or processing tools are not generally available, and the machine-generated HTML produced
by some word processors for output purposes only.
The ”Title Page” means, for a printed book, the title page itself, plus such following pages as are
needed to hold, legibly, the material this License requires to appear in the title page. For works in
formats which do not have any title page as such, ”Title Page” means the text near the most prominent
appearance of the work’s title, preceding the beginning of the body of the text.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially,
provided that this License, the copyright notices, and the license notice saying this License applies to
the Document are reproduced in all copies, and that you add no other conditions whatsoever to those
of this License. You may not use technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept compensation in exchange
for copies. If you distribute a large enough number of copies you must also follow the conditions in
section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100, and the Document’s license
notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover.
Both covers must also clearly and legibly identify you as the publisher of these copies. The front
cover must present the full title with all words of the title equally prominent and visible. You may add
other material on the covers in addition. Copying with changes limited to the covers, as long as they
preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying
in other respects.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 32 / 34

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones
listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must ei-
ther include a machine-readable Transparent copy along with each Opaque copy, or state in or with
each Opaque copy a publicly-accessible computer-network location containing a complete Transpar-
ent copy of the Document, free of added material, which the general network-using public has access
to download anonymously at no charge using public-standard network protocols. If you use the lat-
ter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in
quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until
at least one year after the last time you distribute an Opaque copy (directly or through your agents
or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistribut-
ing any large number of copies, to give them a chance to provide you with an updated version of the
Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2
and 3 above, provided that you release the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus licensing distribution and modification of the
Modified Version to whoever possesses a copy of it. In addition, you must do these things in the
Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and
from those of previous versions (which should, if there were any, be listed in the History section of
the Document). You may use the same title as a previous version if the original publisher of that
version gives permission. B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified Version, together with at least
five of the principal authors of the Document (all of its principal authors, if it has less than five).
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice
for your modifications adjacent to the other copyright notices. F. Include, immediately after the
copyright notices, a license notice giving the public permission to use the Modified Version under
the terms of this License, in the form shown in the Addendum below. G. Preserve in that license
notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license
notice. H. Include an unaltered copy of this License. I. Preserve the section entitled ”History”,
and its title, and add to it an item stating at least the title, year, new authors, and publisher of
the Modified Version as given on the Title Page. If there is no section entitled ”History” in the
Document, create one stating the title, year, authors, and publisher of the Document as given
on its Title Page, then add an item describing the Modified Version as stated in the previous
sentence. J. Preserve the network location, if any, given in the Document for public access to a
Transparent copy of the Document, and likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the ”History” section. You may omit
a network location for a work that was published at least four years before the Document itself,
or if the original publisher of the version it refers to gives permission. K. In any section entitled
”Acknowledgements” or ”Dedications”, preserve the section’s title, and preserve in the section
all the substance and tone of each of the contributor acknowledgements and/or dedications given
therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in
their titles. Section numbers or the equivalent are not considered part of the section titles. M.
Delete any section entitled ”Endorsements”. Such a section may not be included in the Modified
Version. N. Do not retitle any existing section as ”Endorsements” or to conflict in title with any
Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary
Sections and contain no material copied from the Document, you may at your option designate some
or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the
Modified Version’s license notice. These titles must be distinct from any other section titles.
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 33 / 34

You may add a section entitled ”Endorsements”, provided it contains nothing but endorsements of
your Modified Version by various parties—for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as
a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by)
any one entity. If the Document already includes a cover text for the same cover, previously added by
you or by arrangement made by the same entity you are acting on behalf of, you may not add another;
but you may replace the old one, on explicit permission from the previous publisher that added the
old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their
names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms
defined in section 4 above for modified versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections
of your combined work in its license notice.
The combined work need only contain one copy of this License, and multiple identical Invariant Sec-
tions may be replaced with a single copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique by adding at the end of it, in paren-
theses, the name of the original author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of
the combined work.
In the combination, you must combine any sections entitled ”History” in the various original docu-
ments, forming one section entitled ”History”; likewise combine any sections entitled ”Acknowledge-
ments”, and any sections entitled ”Dedications”. You must delete all sections entitled ”Endorsements.”
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this Li-
cense, and replace the individual copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the rules of this License for verbatim copying
of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this
License, provided you insert a copy of this License into the extracted document, and follow this License
in all other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or
works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified
Version of the Document, provided no compilation copyright is claimed for the compilation. Such a
compilation is called an ”aggregate”, and this License does not apply to the other self-contained works
thus compiled with the Document, on account of their being thus compiled, if they are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if
the Document is less than one quarter of the entire aggregate, the Document’s Cover Texts may be
placed on covers that surround only the Document within the aggregate. Otherwise they must appear
on covers around the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document
under the terms of section 4. Replacing Invariant Sections with translations requires special permis-
sion from their copyright holders, but you may include translations of some or all Invariant Sections
in addition to the original versions of these Invariant Sections. You may include a translation of
Getting Started V2.9.4-5-g9a3aa17b34, 25 Jan 2025 34 / 34

this License provided that you also include the original English version of this License. In case of a
disagreement between the translation and the original English version of this License, the original
English version will prevail.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for
under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void,
and will automatically terminate your rights under this License. However, parties who have received
copies, or rights, from you under this License will not have their licenses terminated so long as such
parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation
License from time to time. Such new versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See https://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that
a particular numbered version of this License ”or any later version” applies to it, you have the option
of following the terms and conditions either of that specified version or of any later version that has
been published (not as a draft) by the Free Software Foundation. If the Document does not specify
a version number of this License, you may choose any version ever published (not as a draft) by the
Free Software Foundation.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document
and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this doc-
ument under the terms of the GNU Free Documentation License, Version 1.1 or any later version
published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES,
with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license
is included in the section entitled ”GNU Free Documentation License”.
If you have no Invariant Sections, write ”with no Invariant Sections” instead of saying which ones
are invariant. If you have no Front-Cover Texts, write ”no Front-Cover Texts” instead of ”Front-Cover
Texts being LIST”; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we recommend releasing these exam-
ples in parallel under your choice of free software license, such as the GNU General Public License,
to permit their use in free software.