Upgrade Your 3D Printer with Klipper: A Complete Setup Guide

Klipper is a 3D printer firmware that offloads motion planning calculations from the printer’s microcontroller to a Raspberry Pi or similar single-board computer. The result is faster print speeds (300-500mm/s on a tuned Voron), pressure advance for cleaner corners, input shaping to kill ringing artifacts, and real-time configuration changes with no re-flashing. As of 2026, Klipper paired with a Mainsail or Fluidd web UI running on a Raspberry Pi 5 or Orange Pi 5 Plus is the default stack for anyone serious about 3D printing.

If you’re still running Marlin or stock Creality firmware, this guide walks you through what Klipper actually does differently, what hardware you need, how to install and configure it from scratch, and how to tune input shaping and pressure advance - the two changes that will make the biggest visual difference to your prints.

What Klipper Does Differently (and Why It Matters)

The core difference between Klipper and traditional firmware like Marlin is architectural. On a Marlin printer, the mainboard’s microcontroller handles everything: G-code parsing, motion planning, acceleration calculations, and the actual step pulse generation. That 32-bit MCU is doing a lot of work, and it hits a ceiling fairly quickly at higher speeds.

Klipper splits the job across two systems. A host computer - a Raspberry Pi 5, an Orange Pi 5 Plus, or even a small x86 mini PC - runs the main Klipper process and handles all the G-code parsing and motion planning. The printer’s existing mainboard (an SKR Mini E3, BTT Octopus, stock Creality board using STM32/LPC1768) runs a stripped-down Klipper MCU firmware that only executes pre-computed step sequences with microsecond-level timing. More than 90% of the computational work moves off the microcontroller onto the host.

This architecture makes several things possible that stock firmware can’t do:

Input shaping (resonance compensation) works by mounting an ADXL345 accelerometer to the toolhead carriage. The Pi measures resonance frequencies at various print speeds, then computes an input shaping filter - ZV, MZV, EI, or 2HUMP_EI - that cancels the ringing artifacts that show up as ghosting/rippling around sharp edges. Printers that produce visible ringing at 80mm/s on Marlin can run cleanly at 200mm/s or more under Klipper with a properly tuned input shaper.

Pressure advance addresses a separate problem: filament pressure builds up inside the hotend as it accelerates and releases as it decelerates, causing corner blobs and gaps. Klipper compensates by adjusting the extruder motor ahead of direction changes. It works better than Marlin’s linear advance and can be tuned per-filament profile.

Live configuration is simpler than it sounds. Edit printer.cfg in the Mainsail web interface, run FIRMWARE_RESTART, and the change takes effect immediately - no recompiling, no SD card, no reflashing. For iterative calibration work, this matters a lot.

The Moonraker API layer ties it all together: Crowsnest for webcam streaming, timelapse plugins, KlipperScreen for touchscreen control, Klipper Expander boards for extra I/O, and direct slicer integration with OrcaSlicer and PrusaSlicer.

Hardware Requirements and Compatible Printers

Choosing a Host Computer

The Raspberry Pi 5 4GB ($60) is the recommended host in 2026. It handles webcam streaming, Klipper processing, and Moonraker without any bottleneck. The Orange Pi 5 Plus ($55) is a faster and slightly cheaper alternative with 8GB RAM and more USB ports - a reasonable swap if you can’t get a Pi 5.

Older Pi 3B or Pi 4 units work, but they start to struggle when you’re simultaneously streaming a webcam, running Klipper at high print speeds, and serving the Mainsail UI. If you already have a Pi 4 lying around, it’s fine to start with, but budget for a Pi 5 if you’re buying new hardware.

Printer Compatibility

Most printers with a replaceable or flashable mainboard are compatible with Klipper. The table below covers the common ones:

For an Ender 3 running the stock Creality 4.2.7 board, you can flash Klipper directly via the STM32F103 target. The minimum cost to get Klipper running is around $60 for a Pi Zero 2W plus $0 if you flash the existing board. For a cleaner install with better headroom, a Pi 5 4GB ($60) plus a BTT SKR Mini E3 V3 ($30) is a better foundation.

For Voron-class builds, the BigTreeTech Octopus v1.1 and Manta M8P are the go-to control boards. Both support multiple TMC2209/2226 stepper drivers, CAN bus for the toolhead, and 24V input.

CANBUS Toolhead Boards

The BigTreeTech EBB36 and EBB42 toolhead boards connect via a single 4-wire CAN cable and carry all toolhead signals: thermistor, heater, fans, ADXL345, and probe. This cuts the cable chain on an enclosed printer down considerably. If you’re doing a Voron build or a significant Ender 3 rebuild, adding CAN bus from the start is worth it.

Installing Klipper, Moonraker, and Mainsail

The KIAUH Installer

The standard installation path is KIAUH (Klipper Installation And Update Helper). Clone it onto a fresh Raspberry Pi OS Lite install and run the interactive menu:

git clone https://github.com/dw-0/kiauh && cd kiauh && ./kiauh.sh

KIAUH installs Klipper, Moonraker, and your choice of web UI in 10-15 minutes. It handles service setup, Python virtual environments, and dependencies. When it asks which UI to install, choose one:

• Mainsail has a cleaner UI, better macro management, and is the default for Voron builds
• Fluidd is slightly more beginner-friendly with better inline documentation

Either works. Pick Mainsail unless you have a specific reason to prefer Fluidd.

Flashing the MCU

After KIAUH finishes, flash the printer’s mainboard with Klipper’s MCU firmware:

cd ~/klipper && make menuconfig

Select the correct target for your board. Common examples:

• Ender 3 4.2.7 stock board: STM32F103
• BTT SKR Mini E3 V3: STM32G0B1
• BTT Octopus v1.1: STM32F446

Compile with make, then copy the resulting klipper.bin to an SD card (rename to firmware.bin for most Creality boards) or flash via USB DFU mode depending on the board’s requirements.

Initial printer.cfg Configuration

Download the community-maintained config file from the Klipper config directory for your specific printer. Adjust three things before first boot:

1. The serial: path - find yours with ls /dev/serial/by-id/ after connecting via USB
2. The [stepper_*] endstop pin assignments for your specific wiring
3. The [extruder] thermistor type (NTC 100K B3950, ATC Semitec 104GT-2, etc.)

Connect to Mainsail at http://klipper.local (or the Pi’s IP), open the terminal tab, and run STATUS. You should see “Klipper state: Ready”. Jog the axes manually to verify motor direction and endstop behavior before attempting any print.

Moonraker Configuration

In moonraker.conf, configure update_manager to pull upstream updates for Klipper, Moonraker, and Mainsail automatically. Add the timelapse plugin config if you’re running a webcam. Moonraker’s API also enables direct print-from-slicer integration with OrcaSlicer and PrusaSlicer.

Tuning Input Shaping and Pressure Advance

These two calibration steps produce the most visible improvement in print quality. Do them before tweaking anything else.

Mounting and Running the ADXL345

Mount an ADXL345 accelerometer to the toolhead carriage using M3 screws - not the nozzle or fan duct, which will pick up noise from cooling and hotend vibration. Print the appropriate mount for your printer from Printables or the Klipper community.

Wire the ADXL345 to the Pi’s SPI GPIO pins:

• MOSI: GPIO10
• MISO: GPIO9
• SCK: GPIO11
• CS: GPIO8

Add the following sections to printer.cfg:

[adxl345]
cs_pin: rpi:None
spi_software_sclk_pin: rpi:gpio11
spi_software_mosi_pin: rpi:gpio10
spi_software_miso_pin: rpi:gpio9

[resonance_tester]
accel_chip: adxl345
probe_points: 100, 100, 20

Run the calibration from the Mainsail terminal:

TEST_RESONANCES AXIS=X
TEST_RESONANCES AXIS=Y

Klipper writes CSV data files to /tmp/. Generate the calibration graphs:

~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png

Interpreting Shaper Output

The script recommends a shaper type and frequency. Look at the “remaining vibrations” percentage for each option. ZV is the fastest but least effective on high-resonance printers. MZV gives a reasonable balance of speed and vibration reduction. EI applies slightly more aggressive smoothing and handles higher resonance. 2HUMP_EI goes furthest on resonance reduction but costs some speed.

MZV or EI are the right choice for most printers. Apply the recommendation to printer.cfg:

[input_shaper]
shaper_freq_x: 48.2
shaper_type_x: mzv
shaper_freq_y: 41.6
shaper_type_y: mzv

Pressure Advance Tuning

Print a pressure advance calibration tower using:

SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500

Inspect the corners at different PA values. Typical ranges:

• Direct drive extruder: 0.03-0.06
• Bowden extruder: 0.4-0.8

Once you find the right value, store it in the slicer’s filament start G-code:

SET_PRESSURE_ADVANCE ADVANCE=0.045

OrcaSlicer 2.2 is the community-preferred slicer for Klipper users in 2026. It has built-in Klipper calibration print support and direct integration with Moonraker for sending prints from the slicer.

Advanced Klipper: Macros, Multi-Material, and CANBUS

G-code Macros

Klipper macros are Jinja2 templates. They can branch on printer state, call other macros, and accept parameters. The most important macro to get right is PRINT_START. A solid implementation:

1. Heat the bed to target temperature
2. Run BED_MESH_CALIBRATE for automatic bed leveling
3. Heat soak for ABS/ASA until chamber hits target temperature
4. Run a purge line
5. Hand off to the print

The community repo A-better-print_start-macro has a production-ready version worth copying as a starting point.

Exclude Objects is another macro feature worth enabling. With OrcaSlicer and Klipper’s [exclude_object] module, you can cancel a single failing object mid-print without stopping the entire plate. If something starts warping, run EXCLUDE_OBJECT NAME=object_name in the console and Klipper skips it.

CANBUS with EBB36/42

To add a CAN bus toolhead board, set up the can0 interface on the Pi and add an MCU section to printer.cfg:

[mcu EBBCan]
canbus_uuid: your-uuid-here

Find the UUID with python3 ~/klipper/lib/canboot/flash_can.py -q. The EBB36/42 boards carry all toolhead signals over a single 4-wire cable. This is a significant wiring simplification for enclosed printers with complex cable chains.

The Klipper Shake&Tune plugin improves on the default resonance calibration workflow with better graphs, more detailed recommendations, and standalone per-axis frequency characterization. Install it via KIAUH’s extension menu.

Multi-Material Printing

The ERCF (Enraged Rabbit Carrot Feeder) and Tradrack are the two main multi-material systems for Klipper. Both run Happy Hare MMU firmware , which adds automatic filament loading, unloading, tip forming, and purge tower management. In 2026, a tuned ERCF setup can handle 6-12 colors on a single printhead.

Troubleshooting Common Klipper Issues

“MCU not found” almost always means the USB serial path is wrong. Run ls /dev/serial/by-id/ and verify the path matches the serial: value in printer.cfg. Also check that the MCU firmware was correctly flashed - if the board still has stock firmware, Klipper won’t recognize it.

Lost USB connection during a print is usually a cable problem. Use a quality shielded USB cable and add ferrite cores near both ends. If it keeps happening, switch to UART communication between the Pi and the mainboard - it’s generally more stable than USB across long prints.

Homing failures are often a pin assignment problem. Run QUERY_ENDSTOPS in the Mainsail terminal while manually triggering each endstop to see what Klipper reports. An inverted endstop logic - missing the ! prefix in the pin definition - is the most common culprit.

Thermal safety is worth verifying before your first print. Klipper’s runaway protection is the [verify_heater] config section. Make sure it’s in your printer.cfg:

[verify_heater extruder]
max_error: 120
check_gain_time: 20
hysteresis: 5
heating_gain: 2

Without this section, Klipper will not detect a runaway heater condition. Check it’s there before printing.

Klipper has no native power-loss resume, unlike Marlin. The third-party power_loss_recovery plugin adds this capability, but it’s not as reliable as Marlin’s implementation. On an enclosed ABS printer running multi-hour prints, a UPS is a more practical solution than software recovery.

Backing Up Your Klipper Configuration

printer.cfg represents weeks or months of tuning work. Treat it like production code.

The simplest approach is git version control:

cd ~/printer_data/config
git init
git add printer.cfg moonraker.conf
git commit -m "initial config"

Moonraker’s backup plugin can automate pushes to a private GitHub or Gitea repo after every config change. Configure it in moonraker.conf:

[backup]
host: github.com
port: 22
folder: ~/printer_data/config
service: git_repo
path: your-repo-name

A corrupted SD card, a failed OS upgrade, or an accidental rm during maintenance can wipe everything. A remote git backup means recovery is a git clone away. This is especially important for CAN bus setups and multi-material configurations, where the config complexity is significantly higher.

Running Klipper changes how 3D printing actually works, not just how fast it goes. The first input shaping calibration run - watching ringing disappear on prints that previously looked like they had corduroy texture at speed - is the moment most people stop thinking of it as optional.