How to Install Klipper: Raspberry Pi, Mainsail, and Your First Config

Klipper moves the heavy motion planning off your printer’s slow 8-bit or 32-bit board and onto a Raspberry Pi. The result is faster prints, cleaner corners, and a printer you configure by editing a text file instead of reflashing firmware. The whole setup takes about 60 to 90 minutes, and you can do it with a Pi, a microSD card, and a USB cable.

Quick Takeaways

• Fastest path: Flash Mainsail OS with Raspberry Pi Imager. Klipper, Moonraker, and the Mainsail web UI come preinstalled.
• Two firmware steps: Klipper runs on the Pi, and a small Klipper firmware runs on your printer’s mainboard (the MCU). Both are required.
• One file controls everything: printer.cfg replaces Marlin’s compiled Configuration.h. Changes apply with a single restart, no reflashing.
• Minimum hardware: A Raspberry Pi 3B+ or newer (Pi 4, Pi 5, and Zero 2 W all work), a 16 GB+ A1/A2 microSD card, and a quality power supply.

What You Need Before You Start

Check that your board appears in the config/ folder of the Klipper repository on GitHub. Sample configs there give you the exact pin mappings and firmware settings for hundreds of printers.

Step 1: Flash Mainsail OS to the SD Card

Mainsail OS is a Raspberry Pi OS Lite image with the full Klipper stack preinstalled and configured. It is the quickest route for a first install.

1. Download and open Raspberry Pi Imager on your computer.
2. Click Choose Device and select your Pi model.
3. Click Choose OS, then Other specific-purpose OS, then 3D printing, then Mainsail OS. Pick the Raspberry Pi build that matches your model.
4. Click Choose Storage and select your microSD card.
5. Click Next, then Edit Settings when asked about OS customization.

In the customization screen, set these values:

Write the card, insert it into the Pi, and power it on. First boot takes 2 to 4 minutes. Wired Ethernet is more stable than Wi-Fi for long prints, so use it when you can.

Alternative: Install with KIAUH

If you already run Raspberry Pi OS Lite, install the stack with the Klipper Installation And Update Helper (KIAUH):

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

In the menu, choose Install, then install Klipper, Moonraker, and Mainsail in that order. Accept the defaults unless you run several printers on one Pi.

Step 2: Connect to Mainsail and SSH

Open a browser on any device on the same network and go to:

http://mainsailos.local

If the hostname does not resolve, find the Pi’s IP address in your router’s client list and use that instead. You will see the Mainsail dashboard, probably with a red “MCU not connected” error. That is expected because the mainboard has no Klipper firmware yet.

Open a terminal and connect over SSH (replace the username and hostname with yours):

ssh youruser@mainsailos.local

Step 3: Build and Flash the Klipper Firmware for Your Mainboard

Klipper’s source lives in ~/klipper. Each board needs its own firmware build, and wrong settings here are the most common cause of failed installs.

Open the build menu

cd ~/klipper
make menuconfig

Choose settings for your board

Look at the header comment of your board’s sample file in ~/klipper/config/. It lists the exact values. The table below shows a typical example for a Creality-style STM32F103 board. Treat it as an illustration and always verify against your own board’s file.

Press Q, then Y to save. Build the firmware:

make clean
make

The output file is ~/klipper/out/klipper.bin (some boards use .uf2 or .hex).

Flash the firmware

Flashing varies by board family:

SD card flashing rules:

1. Format the card as FAT32 (32 GB or smaller works best).
2. Rename the file to something unique each time, such as klipper-0112.bin. Many bootloaders ignore a filename they have already flashed.
3. Insert the card, power-cycle the printer, wait about 30 seconds, then remove the card.

Copy the file from the Pi to your computer with scp:

scp youruser@mainsailos.local:~/klipper/out/klipper.bin ./klipper-0112.bin

Step 4: Find the Serial ID of Your MCU

Connect the printer to the Pi with the USB cable, power on the printer, and run:

ls /dev/serial/by-id/*

You should see a path like this:

/dev/serial/by-id/usb-Klipper_stm32f103xe_36FFD...-if00

Copy it exactly. If the command says “No such file or directory”, the firmware did not flash, the USB cable is power-only, or the board settings in menuconfig were wrong. Re-check those three things in that order.

Step 5: Write Your First printer.cfg

In Mainsail, open the Machine tab (the file list on the left) and edit printer.cfg. Mainsail OS places the file at ~/printer_data/config/printer.cfg.

The example below targets a Cartesian bed-slinger with an Ender 3-style 4.2.2 board and a direct Z endstop. Pin names are board-specific. Copy pins from your own board’s sample config in ~/klipper/config/ and use this file as a structural template.

[include mainsail.cfg]

[mcu]
serial: /dev/serial/by-id/REPLACE_WITH_YOUR_ID

[printer]
kinematics: cartesian
max_velocity: 300
max_accel: 3000
max_z_velocity: 5
max_z_accel: 100

[stepper_x]
step_pin: PC2
dir_pin: PB9
enable_pin: !PC3
microsteps: 16
rotation_distance: 40
endstop_pin: ^PA5
position_endstop: 0
position_max: 235
homing_speed: 50

[stepper_y]
step_pin: PB8
dir_pin: PB7
enable_pin: !PC3
microsteps: 16
rotation_distance: 40
endstop_pin: ^PA6
position_endstop: 0
position_max: 235
homing_speed: 50

[stepper_z]
step_pin: PB6
dir_pin: !PB5
enable_pin: !PC3
microsteps: 16
rotation_distance: 8
endstop_pin: ^PA7
position_endstop: 0.0
position_max: 250

[extruder]
step_pin: PB4
dir_pin: PB3
enable_pin: !PC3
microsteps: 16
rotation_distance: 33.683
nozzle_diameter: 0.400
filament_diameter: 1.750
heater_pin: PA1
sensor_type: EPCOS 100K B57560G104F
sensor_pin: PC5
control: pid
pid_Kp: 21.527
pid_Ki: 1.063
pid_Kd: 108.982
min_temp: 0
max_temp: 250

[heater_bed]
heater_pin: PA2
sensor_type: EPCOS 100K B57560G104F
sensor_pin: PC4
control: pid
pid_Kp: 54.027
pid_Ki: 0.770
pid_Kd: 948.182
min_temp: 0
max_temp: 130

[heater_fan hotend_fan]
pin: PC0
heater: extruder
heater_temp: 50.0

[fan]
pin: PA0

What the key lines do:

• [include mainsail.cfg] loads the macros and settings Mainsail needs (PAUSE, RESUME, CANCEL_PRINT, the virtual SD card). Without it, Mainsail will not print files.
• rotation_distance replaces Marlin’s steps-per-mm. For belts, it equals belt pitch times pulley teeth (2 mm × 20 teeth = 40). For an 8 mm lead screw, it is 8.
• The ! prefix inverts a pin. The ^ prefix enables the internal pull-up.
• control: pid with starting values is a placeholder. You will tune it in Step 7.

Click Save & Restart. Mainsail should change from “Error” to “Ready.” If it shows an error, read the message at the top of the dashboard. Klipper reports the exact line and key that caused it.

Step 6: First Power-On Checks (Do These Before Printing)

Run each test from the Mainsail console and confirm the result. Keep a finger near the power switch for the first movement tests.

If an axis moves the wrong direction, add or remove the ! on its dir_pin. Do not swap motor cables.

Step 7: Calibrate PID and Save

Run PID tuning on both heaters at your typical printing temperatures:

PID_CALIBRATE HEATER=extruder TARGET=200
SAVE_CONFIG
PID_CALIBRATE HEATER=heater_bed TARGET=60
SAVE_CONFIG

SAVE_CONFIG writes results to an auto-generated block at the bottom of printer.cfg and restarts Klipper. Do not edit that block by hand.

Next, set your Z offset. With a mechanical Z endstop:

G28
Z_ENDSTOP_CALIBRATE

Use the paper test to lower the nozzle until it grips a sheet lightly, then run ACCEPT and SAVE_CONFIG.

Klipper vs. Marlin: What Changes

Mainsail vs. Fluidd

Both use the same backend. You can switch later without touching printer.cfg.

Real-World Use Cases

• Speeding up a stock Ender 3: Users commonly raise print acceleration from Marlin’s conservative defaults to 3,000-5,000 mm/s² once Pressure Advance and Input Shaper are tuned, cutting print time noticeably without large quality loss.
• Voron and CoreXY builds: Klipper is the standard firmware on Voron printers. Its kinematics support CoreXY, CoreXZ, Delta, and CoreXY with quad gantry leveling (QUAD_GANTRY_LEVEL).
• Print farms: One Pi per printer, each with a unique hostname, lets you manage fleets from a browser. Update Manager in Mainsail keeps every unit on the same Klipper and Moonraker versions.
• Remote monitoring: The preinstalled crowsnest webcam service streams video into the Mainsail dashboard. Connect a USB camera and print from anywhere on your network.
• Fast iteration on tuning: Because config edits take seconds, you can compare retraction, pressure advance, and temperatures across test prints in a single afternoon.

Next Tuning Steps

Once the printer produces a good first layer, work through these in order:

1. Pressure Advance: Print a tower and find the cleanest corner.

SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500
TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005

Typical starting ranges are 0.04-0.10 for direct drive and 0.5-1.0 for Bowden setups. Add the winning value to [extruder] as pressure_advance: 0.XX.

2. Input Shaper: Install an ADXL345 accelerometer, then run SHAPER_CALIBRATE. Add the recommended shaper type and frequency to [input_shaper].
3. Bed mesh: Add a probe and [bed_mesh] if your bed is not flat.
4. Slicer start G-code: Use PRINT_START macros so your slicer passes temperatures into Klipper.

A minimal macro looks like this:

[gcode_macro PRINT_START]
gcode:
    {% set BED = params.BED|default(60)|float %}
    {% set EXTRUDER = params.EXTRUDER|default(200)|float %}
    M140 S{BED}
    M104 S{EXTRUDER - 50}
    G28
    M190 S{BED}
    M109 S{EXTRUDER}

In your slicer’s start G-code field, enter:

PRINT_START BED=[first_layer_bed_temperature] EXTRUDER=[first_layer_temperature]

(Placeholder syntax differs per slicer. This example uses PrusaSlicer/SuperSlicer-style variables.)

Troubleshooting Common Install Errors

Check live logs from SSH when an error is not obvious:

tail -f ~/printer_data/logs/klippy.log
sudo journalctl -u klipper -f

Restart services without rebooting:

sudo service klipper restart
sudo service moonraker restart

FAQ

Can I run Klipper on a Raspberry Pi Zero or Pi 3?

Yes. A Pi 3B+ and Pi Zero 2 W both run Klipper, Moonraker, and Mainsail for a single printer. A Pi 4 or Pi 5 gives headroom for webcams, input shaper calibration, and multiple printers.

Do I need to flash firmware to my printer board if I use Mainsail OS?

Yes. Mainsail OS installs the software on the Pi only. Your mainboard needs its own Klipper firmware build, because Klipper’s host and MCU software work as a pair.

Is Klipper better than Marlin?

Klipper offloads motion math to the Pi, which allows higher speeds and finer tuning tools such as Pressure Advance and Input Shaper. Marlin is simpler because it needs no extra computer. For printers where speed and tunability matter, Klipper is the stronger option.

Where is the Klipper config file located?

On Mainsail OS, printer.cfg sits in ~/printer_data/config/. Edit it from the Mainsail Machine tab, then click Save & Restart.