Klipper Install Guide: Klipper, KIAUH, Moonraker and Mainsail Explained

Latest Versions of Every Part

How this table works

• It is live. Each visit asks GitHub for the newest release of Mainsail and Fluidd, and for the highest version tag of Klipper, KIAUH and Moonraker, which publish version tags and no usable release feed. Your browser keeps the answer for ten minutes; the Refresh button asks again straight away.
• You normally do not download these by hand. KIAUH fetches and installs them for you (see the steps below). The table tells you what a fresh install should give you and links to the source.
• The zip files are for people who set things up manually. Mainsail and Fluidd are published as a single zip that a web server serves; the links only point to files on each project’s own GitHub release path.
• Klipper itself is a rolling project. Installations usually follow the main branch of its repository, and a version tag such as the one shown marks a release milestone. Klipper’s own release page lists tagged releases from 0.9.0 in October 2020 to 0.13.0 in April 2025.

What Is Klipper?

Every 3D printer has a control board with a small microcontroller. Traditionally the firmware on that board does everything: it reads G-code, plans the motion, times every motor step and watches the heaters. Klipper changes that division of labour. A host computer (a Raspberry Pi or a similar Linux machine) runs the demanding part, the G-code processing and motion planning, and sends scheduled commands to the printer’s microcontroller, which only has to carry them out on time. Klipper’s code overview describes the host program as written mainly in Python with some C helpers, and the microcontroller code as C.

Klipper is released under the GNU General Public License v3 (GPL-3.0), and the project is open on GitHub. According to its documentation it schedules each stepper event with a precision of 25 microseconds or better, supports printers with several microcontrollers, and is hardware agnostic: it runs on ARM, AVR, PRU and other microcontroller families.

The Parts of the Stack

How the Pieces Fit Together

The key idea is that the heavy thinking happens on the host. Klipper’s code overview explains that the host calculates the exact step times for each stepper, compresses them and sends them to the microcontroller, which queues the commands (typically at least 100 ms before the first step) and generates each pulse from a hardware timer interrupt at the scheduled moment. That is why a cheap 8-bit board can still move quickly, and why the host connection matters: if Klipper loses contact with the board mid-print, the print stops.

Moonraker is the translator in the middle. Klipper has its own command interface, but a web interface cannot speak it directly. Moonraker exposes Klipper through a standard web API, which is why Mainsail, Fluidd and many phone apps all work with it. KIAUH sits outside the diagram: it is the helper that installs and updates the pieces on the host.

What You Need

Install Klipper Step by Step

Step 1: Get a configuration file for your printer

Klipper is configured with a text file, printer.cfg. Look in the config/ directory of the Klipper repository for a file named printer- followed by your printer’s name. If there is none, check the printer manufacturer’s website. If you only know the board type, use a generic- file. Writing one from scratch is possible but needs a lot of technical knowledge.

Step 2: Prepare the host computer

1. Write Raspberry Pi OS Lite to an SD card with the Raspberry Pi Imager (the KIAUH README recommends it). In the Imager’s advanced options, enable SSH and enter your Wi-Fi details.
2. Boot the Raspberry Pi and log in over SSH from your computer.

Step 3: Install and start KIAUH

These are the commands from the KIAUH README. Install git, download KIAUH, and start it:

sudo apt-get update && sudo apt-get install git -y
cd ~ && git clone https://github.com/dw-0/kiauh.git
./kiauh/kiauh.sh

KIAUH shows a menu; type the number of the action you want at the prompt and press Enter. It asks for your sudo password when it needs it.

Step 4: Install Klipper, Moonraker and a web interface

1. In KIAUH’s install menu, install Klipper first.
2. Then install Moonraker. Its documentation says Klipper should be installed first.
3. Then install a web interface: Mainsail or Fluidd (or OctoPrint, which Klipper’s guide also lists as an option). If you want a touchscreen, KIAUH can add KlipperScreen later.

Step 5: Build and flash the control-board firmware

The printer’s microcontroller needs Klipper’s own firmware. From Klipper’s installation guide:

cd ~/klipper/
make menuconfig
make

In make menuconfig, apply the settings listed in the comments at the top of your printer configuration file, press Q to leave and Y to save. Then find the board’s serial port and flash it. The method depends on the board:

The commands used for the Atmega case look like this (put your own port in place of the example):

ls /dev/serial/by-id/*
sudo service klipper stop
make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0
sudo service klipper start

Step 6: Copy your configuration and set the serial port

1. Copy your configuration file to the printer configuration folder of the host. The built-in editors in Mainsail and Fluidd work, as do SCP or SFTP tools and SSH. As a basic example, Klipper’s guide copies an example file and opens it in an editor:

   cp ~/klipper/config/example-cartesian.cfg ~/printer.cfg
   nano ~/printer.cfg

2. Run ls /dev/serial/by-id/* again, because the name can change after flashing, and put the result in the [mcu] section:

   [mcu]
   serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0

On a typical KIAUH install the configuration files live in ~/printer_data/config/; the Klipper guide’s own examples use ~/printer.cfg. Use the folder that your web interface’s editor shows.

Step 7: Restart, check the status and read the log

Open your web interface in a browser at the host’s address, send the restart command and then check status. Fix every error the status message reports, restart again and repeat until the printer says it is ready. The log, which explains most problems, is usually at ~/printer_data/logs/klippy.log. Then work through the “config check” steps in Klipper’s documentation before you home the printer or heat anything.

First Checks and Tuning

A new Klipper printer should be checked step by step, never started with a full print. The usual order, which Klipper’s configuration-check guide follows, is to confirm the printer reports sensible temperatures, that the heaters respond and stop, that each motor and endstop works in the right direction, and only then to try homing and a first small print. These are general good-practice steps, not a replacement for that guide.

• Temperatures. Read the nozzle and bed temperature at room temperature. Implausible readings mean a wiring or sensor-type setting is wrong.
• Heaters. Watch the first heat-up closely and make sure the readings rise when the heater is on.
• Motion and endstops. Test endstops by hand, and check motor directions with small moves before homing.
• Tuning. After the basics work, Klipper’s pressure advance and input shaping are the features most people turn on. Input shaping is normally tuned with measurements from an accelerometer, which is a small extra purchase.

Slicing is separate. Any slicer that produces G-code for your printer works; slicers such as Orca Slicer and Creality Print can also send jobs straight to a Moonraker-based interface. Mainsail’s documentation lists slicer integration among its features.

Mainsail vs Fluidd vs OctoPrint

You need one web interface. Klipper’s guide lists Mainsail, Fluidd (both built on Moonraker) and OctoPrint as the choices.

The Mainsail and Fluidd rows summarise their documentation and descriptions; OctoPrint has its own guide planned on this site.

Klipper vs Marlin: Is It Right for You?

Updating Klipper and Its Parts

KIAUH is also the update tool: its menus include options to update the software it installed, and its changelog mentions backups before updates and the ability to roll back (including Moonraker). Before you update, read Klipper’s “Config Changes” document, which lists recent software changes that may require edits to your printer configuration file.

• Update when the printer is idle, and not before an important print.
• After updating Klipper, reflash the control-board firmware if the guide for that release says it is needed, since the host and board software must stay compatible.
• Keep a copy of your configuration outside the printer.

Troubleshooting