Disclaimer: This is an independent resource site. Not affiliated with the Voron project or its development team.

Klipper Backup and Restore Guide for Voron — Never Lose Your Config

Klipper Firmware Guide

Your Voron's configuration is the sum of hundreds of hours of tuning — pressure advance values dialed in filament by filament, input shaper resonance curves measured and saved, bed mesh profiles that compensate for every subtle warp in your build plate, and macros that automate your exact workflow. Losing that config to a corrupted SD card, a failed firmware update, or a misconfigured moonraker database is devastating. This guide covers every backup and restore strategy for a Klipper-based Voron, from quick manual saves to fully automated disaster recovery pipelines. Last updated: May 2025.

What You Need to Back Up

A Voron running Klipper has several distinct layers of configuration. Backing up just printer.cfg is not enough for a full recovery. Here is everything that matters:

Method 1: Moonraker Backup Plugin (Recommended)

The moonraker-backup plugin is the most hands-off solution. It creates compressed archives of your entire config directory on a schedule you define and can push them to remote storage via SCP or rsync. 

# In moonraker.conf — enable the backup module
[backup]
enable: True
# Archive the entire ~/printer_data/config directory daily at 3am
# via a cron job on the host:
# 0 3 * * * /home/pi/moonraker/scripts/backup.sh

To install the moonraker backup plugin manually: 

cd ~/moonraker
git pull
./scripts/install-moonraker-backup.sh
# Edit /etc/cron.d/moonraker-backup to set schedule
# Backups land in ~/printer_data/backups/ by default

For off-site backups, add an rsync target in your cron job: 

#!/bin/bash
# ~/printer_data/scripts/backup-to-nas.sh
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p ~/printer_data/backups
cd ~/printer_data
tar czf "backups/config-$TIMESTAMP.tar.gz" config/
rsync -avz --remove-source-files backups/ user@nas:/volume1/voron-backups/

Method 2: Git-Based Backup

Git-based versioning gives you the full power of change history — you can see exactly what you changed between prints, revert a bad tuning change, and maintain branches for different configurations. This is the preferred method for advanced users who want change tracking. 

cd ~/printer_data/config
git init
git add .
git commit -m "Initial config baseline"

# Add a remote (GitHub private repo, or your own Git server)
git remote add origin git@github.com:yourusername/voron-config.git
git branch -M main
git push -u origin main

# Create a backup script with automatic commits
cat > ~/printer_data/scripts/git-backup.sh << 'EOF'
#!/bin/bash
cd ~/printer_data/config
git add -A
git commit -m "Auto-backup $(date +%Y-%m-%d_%H:%M:%S)"
git push origin main
EOF

chmod +x ~/printer_data/scripts/git-backup.sh
# Add to cron: */30 * * * * ~/printer_data/scripts/git-backup.sh

With git-based backup, tracking configuration changes is trivial: 

# See what changed in the last backup
git diff HEAD~1 HEAD

# Show changes for a specific file over time
git log --oneline -p -- printer.cfg

# Revert a bad change
git revert HEAD

Method 3: Manual Backup via SCP/RSync/Samba

For users who prefer a simple, no-dependency approach, manual backup is the most straightforward. Connect to your Raspberry Pi from your desktop and copy files directly. 

# From your desktop — copy entire config directory
scp -r pi@voron.local:~/printer_data/config/ ~/voron-backups/config-$(date +%Y%m%d)

# Using rsync (more efficient for repeated backups)
rsync -avz pi@voron.local:~/printer_data/config/ ~/voron-backups/

# Restore from backup
rsync -avz ~/voron-backups/config/ pi@voron.local:~/printer_data/config/
sudo service klipper restart

If you have Samba set up on the Pi, you can also map the config directory as a network drive on Windows or macOS and copy files through the file explorer. This is the least technical option but works well for quick manual saves before config changes.

Method 4: KIAUH Backup Feature

KIAUH (Klipper Installation And Update Helper) has a built-in backup and restore function that covers the entire Klipper ecosystem. If you used KIAUH to install Klipper, you can run: 

cd ~/kiauh
./kiauh.sh
# Select 4) Advanced -> 9) Backup configuration
# KIAUH creates a timestamped archive of:
#   ~/printer_data/config/
#   ~/klipper/
#   ~/moonraker/
#   ~/klipper-screen/
# Restore via: 4) Advanced -> 10) Restore configuration

The KIAUH backup is comprehensive but manual — you need to run it intentionally. Combine it with one of the automated methods above for complete coverage.

Best Practices

A robust backup strategy for your Voron has two tiers:

Store at least one backup off-device. An SD card failure on the Pi takes out both your live config and any local backups. A NAS, a second Pi, or a private GitHub repository all count as off-device.

Disaster Recovery Scenarios

MCU Firmware Corruption

If your BTT Octopus, SKR Turbo, or Fysetc Spider stops responding (Klipper reports mcu 'mcu': Unable to connect), the firmware may be corrupted. Recover by reflashing via DFU mode: 

# Put the board into DFU mode
# BTT Octopus v1.1: hold BOOT button, press RESET, release BOOT
# Check if detected:
lsusb | grep DFU

# Flash the firmware binary directly
cd ~/klipper
make flash FLASH_DEVICE=0483:df11

# If you saved firmware.bin, you can also copy it to an SD card,
# insert it into the board, and power cycle. The board will
# automatically flash from the SD card.

Moonraker Database Corruption

Moonraker automatically creates a backup file (moonraker.aside) before applying database migrations. If the database becomes corrupted after a failed update: 

sudo service moonraker stop
cp ~/.moonraker_database/moonraker.aside ~/.moonraker_database/moonraker.sqlite
sudo service moonraker start

If the aside file is also corrupted or missing, you can restore from your last full config backup. The database will be rebuilt with saved variables from your save_variables.cfg include file.

SD Card Failure

The Raspberry Pi SD card is the single point of failure in most Voron builds. If it dies completely:

  1. Flash a fresh Raspberry Pi OS image to a new SD card
  2. Install Klipper, Moonraker, and Fluidd/Mainsail via KIAUH
  3. Restore ~/printer_data/config/ from your off-device backup
  4. Recompile and reflash firmware to each MCU from the restored config
  5. Restart Klipper and verify all axes home and heat correctly

MCU Replacement — Config Migration

Replacing a BTT Octopus with a different board (e.g., Octopus v1.1 to v1.2, or Octopus to Spider) means every pin name changes. The migration process: 

# 1. Get the pinout diagram for the new board from the manufacturer
# 2. Map old pin names to new pin names in a spreadsheet
# Example migration: BTT Octopus v1.1 -> Fysetc Spider v2.2
# Octopus: PC0 (stepper X step) -> Spider: PF12 (stepper X step)
# 3. Update printer.cfg with new pin mappings
# 4. Update [mcu] serial path (serial/by-id changes per board)
# 5. Recompile Klipper firmware for the new MCU
# 6. Flash, restart, and test each axis individually

# Find the new serial path
ls -l /dev/serial/by-id/
# Example: usb-Klipper_stm32f446xx_12345-if00

Always keep a copy of your original MCU's Klipper firmware binary alongside your config — if you need to swap back to the original board temporarily, you can reflash without recompiling.

Full Backup Script Example

Here is a comprehensive backup script that covers everything — config directory, moonraker database, and firmware binaries — and pushes them to a remote server: 

#!/bin/bash
# ~/printer_data/scripts/full-backup.sh
# Full Voron Klipper backup — config, database, firmware

BACKUP_DIR=~/printer_data/backups
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BACKUP_FILE="$BACKUP_DIR/voron-full-$TIMESTAMP.tar.gz"
REMOTE_USER="backup"
REMOTE_HOST="192.168.1.100"
REMOTE_PATH="/volume1/voron-backups/"

mkdir -p "$BACKUP_DIR"

# 1. Archive config directory
# 2. Copy moonraker database (stop service first to ensure consistency)
sudo service moonraker stop
cp ~/.moonraker_database/moonraker.sqlite "$BACKUP_DIR/moonraker-$TIMESTAMP.sqlite"
sudo service moonraker start

# 3. Include firmware binaries if they exist
if [ -d ~/klipper/out ]; then
    cp ~/klipper/out/klipper.bin "$BACKUP_DIR/firmware-main-$TIMESTAMP.bin"
fi

# 4. Create compressed archive
tar czf "$BACKUP_FILE" -C ~/printer_data config/     -C "$BACKUP_DIR" "moonraker-$TIMESTAMP.sqlite"     --ignore-failed-read

# 5. Push to remote storage
rsync -avz "$BACKUP_FILE" "$REMOTE_USER@REMOTE_HOST:$REMOTE_PATH"

# 6. Clean up local copies older than 30 days
find "$BACKUP_DIR" -name "voron-full-*.tar.gz" -mtime +30 -delete

echo "Backup complete: $BACKUP_FILE"
echo "Pushed to $REMOTE_HOST:$REMOTE_PATH"

Make the script executable and schedule it in cron: 

chmod +x ~/printer_data/scripts/full-backup.sh
# Add to crontab: 0 3 * * * ~/printer_data/scripts/full-backup.sh

Config Versioning with Git

For serious config management, git-based versioning is the gold standard. Beyond simple backup, it gives you the ability to:

The git diff command is invaluable for debugging — if a print fails after a config change, run git diff HEAD~1 HEAD to see exactly what you changed.

Restore Checklist

When disaster strikes, follow this checklist to get back up and running:

  1. Restore ~/printer_data/config/ from backup
  2. Restore moonraker database from backup or aside file
  3. Verify [mcu] serial paths match the connected hardware
  4. Reflash firmware to each MCU if the SD card or board was replaced
  5. Restart Klipper: sudo service klipper restart
  6. Restart Moonraker: sudo service moonraker restart
  7. Test each axis homes correctly
  8. Test bed heating and extruder heating
  9. Run a bed mesh calibration
  10. Print a calibration cube to verify config integrity

Backup discipline is what separates a frustrating rebuild from a five-minute restore. Pick one of the four methods above — the moonraker plugin for simplicity, or git for power users — and set it up today. Your future self, staring at a dead SD card at 2am, will thank you.

Need Parts for Your Backup-Ready Build?

We source high-quality Voron components — genuine Raspberry Pi 5, industrial-grade SD cards, BTT Octopus boards, LDO stepper motors, and Mean Well PSUs — direct from China factories. Every component is bench-tested before shipping so your Voron runs on reliable hardware. Save 30-50% vs US/EU distributors.

Shop Tested Components →