Skip to content

Installing LinuxCNC 2.10 on Debian Bullseye

I am retrofitting my Weiler Primus CNC to LinuxCNC. Planning the build i was very confused on how to get everything running. This inspired me to dokument every step i took from the very beginning till the end in hopes that this may help you on your conversion. This is not a tutorial but as a reference for your own work. So please keep in mind that everything you do, you do at your own risk.

Youtube Video: LinuxCNC 2.10 installation, Tipps & Tricks

Which hardware do i use?

The PC i’ll be using is called GK41 by Minisforum. It is not the cheapest option, but i think it is well worth it.
It features a small buildvolume, 2 Gigabit Lan Ports, HDMI & Displayport and 4 USB3 Ports.
Also it is delivered with a bracket for easy mounting.
Another handy feature is, that it boots automaticly when it gets power.


First i downloaded the image of Debian 11 from the official website. Choose the latest image “debian-live-amd64-cinnamon+nonfree.iso”

the download can be found here:

I then created a bootable USB Stick with the tool Rufus. Download and description can be found here:

To boot from the USB Stick rund CMD.exe and type :

shutdown.exe /r /o /f /t 00

This will reboot the PC and launch Windows in Save mode. There you can select to boot from the USB Stick.

Installing Debian is quite easy. Just follow the steps and fill out the form when prompted.
When asked for a root password don’t set one. You can create a user password in the next couple steps.

Installing Realtime Kernel

When the system is booted up for the first time, the next step is to install the realtime kernel.

sudo apt install -y linux-image-rt-amd64 linux-headers-rt-amd64 grub-customizer

After that we modify the bootloader Grub, to load Debian with the new Kernel.

sudo grub-customizer

in Grub-customizer we switch to the Tab “General settings”. As default entry we select the realtime Kernel. you can recognize it by the entry “RT”.

I also changed the setting of “boot default entry after” to 0.

The last step is, to add the entry to kernel parameters “isolcpus=3”. This setting is set according to the CPU u are using. I use a 4 core CPU. More info about this setting can be found here:

After rebooting the realtime kernel should be running. We can check by sending in terminal:

uname -a

Next the dependencies for LinunxCNC are installed. Just copy the following Text in the Terminal.

sudo apt install -y geany git debhelper dh-python libudev-dev tcl8.6-dev tk8.6-dev bwidget tclx libeditreadline-dev asciidoc dblatex docbook-xsl dvipng ghostscript graphviz groff imagemagick inkscape python3-lxml source-highlight w3c-linkchecker xsltproc texlive-extra-utils texlive-font-utils texlive-fonts-recommended texlive-lang-cyrillic texlive-lang-french texlive-lang-german texlive-lang-polish texlive-lang-spanish texlive-latex-recommended asciidoc-dblatex python3-dev python3-tk libxmu-dev libglu1-mesa-dev libgl1-mesa-dev libgtk2.0-dev libgtk-3-dev gettext intltool autoconf libboost-python-dev libmodbus-dev libusb-1.0-0-dev psmisc yapps2 libepoxy-dev python3-xlib python3-pyqt5 python3-dbus.mainloop.pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qsci python3-pyqt5.qtmultimedia python3-pyqt5.qtquick qml-module-qtquick-controls gstreamer1.0-plugins-bad  libqt5multimedia5-plugins pyqt5-dev-tools python3-dev python3-setuptools python3-wheel python3-pip python3-yapps dpkg-dev python3-serial libtk-img qttools5-dev qttools5-dev-tools python3-wheel espeak espeak-data espeak-ng freeglut3 gdal-data gstreamer1.0-tools libaec0 libarmadillo10 libarpack2 libcfitsio9 libcharls2 libdap27 libdapclient6v5 libepsilon1 libespeak1 libfreexl1 libfyba0 libgdal28 libgdcm3.0 libgeos-3.9.0 libgeos-c1v5 libgeotiff5 libgif7 libglew2.1 libgtksourceview-3.0-dev libhdf4-0-alt libhdf5-103-1 libhdf5-hl-100 libimagequant0 libkmlbase1 libkmldom1 libkmlengine1 liblept5 libmariadb3 libminizip1 libnetcdf18 libodbc1 libogdi4.1 libopencv-calib3d4.5 libopencv-contrib4.5 libopencv-core4.5 libopencv-dnn4.5 libopencv-features2d4.5 libopencv-flann4.5 libopencv-highgui4.5 libopencv-imgcodecs4.5 libopencv-imgproc4.5 libopencv-ml4.5 libopencv-objdetect4.5 libopencv-photo4.5 libopencv-shape4.5 libopencv-stitching4.5 libopencv-video4.5 libopencv-videoio4.5 libportaudio2 libpq5 libproj19 libprotobuf23 libqhull8.0 librttopo1 libsocket++1 libspatialite7 libsuperlu5 libsz2 libtbb2 libtesseract4 liburiparser1 libxerces-c3.2 libxml2-dev mariadb-common mesa-utils mysql-common odbcinst odbcinst1debian2 proj-bin proj-data python3-configobj python3-espeak python3-gi-cairo python3-olefile python3-opencv python3-opengl python3-pil python3-pil.imagetk python3-pyqt5.qtsvg python3-pyqt5.qtwebkit tcl-tclreadline geotiff-bin gdal-bin glew-utils libgtksourceview-3.0-doc libhdf4-doc libhdf4-alt-dev hdf4-tools odbc-postgresql tdsodbc ogdi-bin python-configobj-doc libgle3 python-pil-doc python3-pil-dbg python3-pil.imagetk-dbg python3-sqlalchemy netcat po4a texlive-lang-european

Afterwards we proceed with cloning the latest Version of LinuxCNC into the Folder “dev”

cd ~
mkdir -p dev/linuxcnc
cd dev/linuxcnc
git clone rip

When the code is downloaded, we now run these commands to build the .deb files.

cd ~/dev/linuxcnc/rip/debian
./configure uspace
cd ..
dpkg-buildpackage -b -uc

I encountered an Error here:
dh_installdocs: error: Cannot find (any matches for) “usr/share/doc/linuxcnc/LinuxCNC_Developer_de.pdf” (tried in ., debian/tmp)

To fix it, we have to modify the rules file in the debian folder:

sudo geany ~/dev/linuxcnc/rip/debian rules

scrolling down you will find

override_dh_installdocs-indep: (around Line 97)

Below are entrys for Languages DE, EN, ES, FR and zh-cn

Delete all but those regarding EN, safe and exit. Retry building the .deb files. It should work now.

cd ~/dev/linuxcnc/rip/
dpkg-buildpackage -b -uc

In the Folder ~/dev/linuxcnc/ you will now find a couple of .deb files. Open the window manager and install linuxcnc-doc-en_2.10.0~pre_amd64.deb and
linuxcnc-uspace_2.10.0~pre_amd64.deb by rightclicking it and selecting open with GDebi Package installer.
LinuxCNC is now installed and can be run from the start menu.

Tipps and Tricks

Auto Login

I want my machine to start up and launch LinuxCNC without interruption. To do this we only have to modify one file:

sudo geany /etc/lightdm/lightdm.conf

Find the section [Seat:*], in there are two entrys. Change #autologin-user= and #autologin-user-timeout=

Change them to autologin-user=*insert your username here* and autologin-user-timeout=0

After rebooting Debian will now automaticly login as the specified user.
With the Application “Startup Applications” you can easily set Programs that are automatically launched after startup.
Here i made a new entry and named it Linuxcnc. The Command, which will start LinuxCNC can be copied from the LinuxCNC shortcut on the desktop (if you have one). Right click on it and select properties. Here you find the command, that is run when you click the icon. Copy it over and your PC will launch LinuxCNC on startup.

Visual Studio Code & LinuxCNC

Download Studio Code here:

After you have installed it go to the extensions Tab. There search for LinuxCNC. After installing the Plugin, Studio Code will now support Syntax Highlighting for LinuxCNC files, which i think is very handy.

Managing LinuxCNC config files with a local git repository

I strongly reccommend to manage your configuration files with a local git repository. The Program i reccommend is called Git cola and can be simply installed with the Software Store application.
After Starting it, create a new Repository and select the configuration Folder of your machine.

On the left you will then see a list of all the changed files. To Initialise the repository we have to stage all files and commit them to it. In the commit summary you should describe what you worked on or what you have changed. Do this everytime after you worked on your config.

Git is a Version control Program. In the Video i didn’t want to explain to much about it and gave a very brief overfiew. If you have not worked with Git yet, i recommend to look for other peoples Youtube videos or reading the docu here:

LinuxCNC Logos

I wanted to make Chip, the Penguin holding the mill bit in the LinuxCNC Icon, hold a lathe tool. While looking for the original files i found the thread on the linuxcnc forum, where the logo was originally uploaded the first time.

Here i found the original file. I cleaned it up a bit, for example the glasses where pretty messed up in the original version. After that i generated an LinuxCNC icon for a Lathe, Lasercutter, Plasmacutter and a Waterjet cutter. The Icons can be downloaded here: