Voron Klipper Update Manager Guide — Automatic Updates and Version Control

Klipper Firmware Guide

Klipper's update manager is one of its most powerful features. It automates firmware updates, keeps your configuration files in version control, and lets you update everything — Klipper, Moonraker, Mainsail, and your printer config — from a single web interface. For Voron owners, this means less time SSH'ing into the Pi and more time printing. Last updated: May 2025.

How the Update Manager Works

The update manager is a Moonraker component that monitors git repositories for new commits. It checks for updates on a configurable interval and reports available updates to the frontend (Mainsail or Fluidd). You can then apply updates with a single click from the web UI. The system tracks these components:

• Klipper firmware — the core firmware repository
• Moonraker — the API server that connects Klipper to the web interface
• Mainsail or Fluidd — the web frontend
• KlipperScreen — the touchscreen interface (if installed)
• Client-side repositories — your printer config, custom macros, and any fork or plugin you add

Default Update Manager Configuration

When you install Klipper via KIAUH or a Voron image, the update manager is preconfigured. You can verify and customize the configuration in Moonraker's config file:

{ast }{ ast }
# ~/printer_data/config/moonraker.conf

[update_manager]
enable_auto_refresh: True
channel: dev

The channel option controls which update branch Klipper tracks:

• dev — tracks the master branch (stable releases, recommended for most users)
• beta — tracks release candidate branches (for testing new features)
• stable — tracks only tagged release versions (most conservative)

Adding Your Printer Config to the Update Manager

One of the best practices is to put your printer configuration in a git repository and add it to the update manager. This gives you version history, rollback capability, and one-click updates:

{ast }{ ast }
# ~/printer_data/config/moonraker.conf

[update_manager printer-config]
type: git_repo
path: ~/printer_data/config
origin: https://github.com/yourusername/voron-printer-config.git
primary_branch: main
enable_auto_refresh: True

Setting Up Git for Your Config

First, initialize a git repository in your config directory:

cd ~/printer_data/config
git init
git add -A
git commit -m "Initial commit of Voron printer config"
git remote add origin https://github.com/yourusername/voron-printer-config.git
git push -u origin main

Make sure to add a .gitignore file to avoid committing sensitive data like Moonraker's secrets file or database files:

# .gitignore
*.mdb
*.db
.moonraker.*.conf
secrets/

Adding Custom Macros and Scripts

If you maintain a separate macros or scripts repository, you can add it the same way:

{ast }{ ast }
[update_manager voron-macros]
type: git_repo
path: ~/printer_data/config/macros
origin: https://github.com/yourusername/voron-macros.git
primary_branch: main

Manual Update Procedure

While the update manager handles most updates automatically, you should occasionally perform a manual update with proper safety checks. This is especially important when updating Klipper itself, since firmware updates require re-flashing your MCUs.

Step-by-Step Manual Update

1. Back up your current configuration:

cd ~/printer_data/config
git add -A && git commit -m "Backup before update"

2. Update Klipper via SSH:

cd ~/klipper
git pull
sudo service klipper stop

3. Re-flash your MCU firmware (if Klipper core changed):

cd ~/klipper
make menuconfig
# Configure for your MCU (e.g., STM32, RP2040)
make clean
make

# For USB-connected MCU:
make flash FLASH_DEVICE=/dev/serial/by-id/usb-Klipper_*

# For Raspberry Pi (as secondary MCU):
make flash FLASH_DEVICE=/dev/ttyAMA0

4. Restart Klipper:

sudo service klipper start
sudo service moonraker restart

5. Verify the update in Mainsail/Fluidd under the Machine tab.

Checking Available Versions

You can check the current version and available updates from the command line:

cd ~/klipper
git log --oneline -5
git fetch --tags
git describe --tags

Rollback Strategy

If an update causes issues — print quality degradation, connection problems, or broken macros — you can roll back using git. The update manager tracks the previous state through Moonraker's database.

Rolling Back via Moonraker

Moonraker stores previous versions in its update history. To roll back:

1. Go to the Machine tab in Mainsail/Fluidd.
2. Click the update history icon next to the component you want to roll back.
3. Select a previous version and click Rollback.
4. If Klipper was rolled back, re-flash your MCUs with the older firmware.

Manual Rollback via Git

cd ~/klipper
git log --oneline
# Find the commit hash you want to revert to
git checkout <commit-hash>
sudo service klipper stop
make clean && make
make flash FLASH_DEVICE=/dev/serial/by-id/usb-Klipper_*
sudo service klipper start

For your config repository:

cd ~/printer_data/config
git log --oneline
git checkout <previous-commit-hash>
sudo service klipper restart

Update Manager Best Practices for Voron

• Commit before updating: Always commit your current config before applying updates. This makes rollback trivial.
• Test after Klipper updates: After a Klipper core update, run a small test print (a calibration cube or Voron test shape) before starting long prints.
• Monitor the channel: If you use dev, check the Klipper Discord or GitHub for any known breaking changes before updating.
• Pin Moonraker version: If Moonraker updates cause issues, you can pin to a specific version in the update manager config.
• Back up Moonraker database: The Moonraker database (~/.moonraker_database/) stores update history. Include it in your backup routine.
• Stagger updates on multiple printers: If you maintain multiple Vorons, update one printer first and verify stability before updating the rest.

Troubleshooting Common Update Issues

Update Manager Shows "Unknown"

If the update manager shows unknown status for a component, the git repository may be in a detached HEAD state or the path is incorrect. Re-clone the repository or check the path in moonraker.conf.

Flash Fails After Update

Sometimes an update changes the required Kconfig settings. Always run make menuconfig to verify your MCU configuration before building and flashing. Common causes: microcontroller architecture changes or bootloader offset changes.

Moonraker Won't Start After Update

Check the Moonraker log for Python dependency issues. A virtual environment update may be needed:

cd ~/moonraker
./scripts/install-moonraker.sh -r

Rollback Corrupted Config

If a config update breaks your printer and you can't access the web UI, recover via SSH:

cd ~/printer_data/config
git reflog
git reset --hard HEAD@{1}

Conclusion

The Klipper update manager transforms what used to be a tedious manual process into a streamlined, version-controlled workflow. For Voron owners, configuring the update manager properly — especially adding your printer config as a managed repository — is one of the highest-ROI setup tasks you can do. It saves time, prevents data loss, and makes the entire maintenance experience far more enjoyable. Take the time to set it up correctly, and future you will thank you.