Klipper-Backup: putting your printer configuration into git

The problem in one sentence: a printer config is a small file you will lose

Klipper-Backup is a script for manual or automated GitHub backups, and the project describes itself as lightweight, pragmatic and comfortable. The homepage is klipperbackup.xyz.

It is worth being clear about what kind of thing this is, because the name suggests a backup suite and it is not that. It is a single-purpose script that takes the configuration files of a Klipper 3D printer and commits them to a git repository on a regular schedule. The repository is the point, not the archive.

That choice comes from the failure mode. A Klipper configuration is a small set of text files, principally printer.cfg and the contents of the config directory, and a bad edit to them can leave a printer that will not start or will heat up wrongly. Without a record, the recovery is reconstructing the file from memory or from a forum post. With a repository, the recovery is a checkout of the last known good commit, and the diff between that and the broken version is the answer to what changed.

The word automated matters as much as the word git. A manual backup is a backup you do not do, and the project description names both manual and automated use, which means the same script covers the one-off save before a firmware change and the recurring commit on a timer.

The topic list names the ecosystem it sits in: 3d-printing, backup, fluidd, git, klipper, mainsail, moonraker, octoprint, restore and shell. The presence of fluidd, mainsail, moonraker and octoprint together is the giveaway that this is meant to run on a printer with a web interface, which is the normal setup for anyone who has a printer configured beyond the defaults.

The project is GPL-3.0 licensed, the primary language is Shell, the default branch is main, and the last push was on 2026-10-13. The recent releases are v1.3.6 on 2026-05-18, v1.3.5 on 2025-11-13 and v1.3.4 on 2025-08-18.

Installing it: a curl command and a setup script

The installation section is two steps, and the first one is a single pipe.

Download:

curl -fsSL get.klipperbackup.xyz | bash

Then the installation and configuration step:

~/klipper-backup/install.sh

So the script is fetched into a klipper-backup directory in your home directory, and the installer is what performs the setup and configuration. The presence of a separate install script rather than a single command that does everything is worth noticing, because it is what lets you inspect what was downloaded before running it, and it is the step where the configuration is created.

The project does not try to hide the detail behind the install script. The README has an RTFM section that suggests reading the docs, with the note that the docs provide detailed step-by-step instructions and further tips. The wording is informal and the author is telling you that the two commands above get the software onto the machine but that the documentation is where the actual setup detail lives.

The documentation site is the same domain as the download URL, and there is a separate configuration page linked from the configuration file itself, at klipperbackup.xyz/configuration, which is where the .env options are documented.

The most recent development is announced at the top of the README. The beta test for the restore function is now open, with a link to the discussion thread that explains more. That is a meaningful signal about the direction of the project, because backup without restore is only half a feature, and the fact that restore is in open beta rather than released says where the remaining work is.

The shell implementation is also part of the design rather than an accident. A printer runs Linux, usually a Raspberry Pi or similar single board computer, and the standard way to schedule a recurring job on one is cron. A shell script that commits and pushes needs nothing more than a git client and a scheduler, which is what makes the lightweight claim credible.

The .env file, and the six values that make it work

The configuration is a single .env file at the root of the repository, and the example file is included so you can see the shape before filling it in. The values are plain shell assignments:

github_token=ghp_xxxxxxxxxxxxxxxx
github_username=USERNAME
github_repository=REPOSITORY
branch_name=main
commit_username=""
commit_email=""

Four of those identify where the backup goes and how it is attributed. The token is a GitHub personal access token, and the username and repository name it should push to. The branch name defaults to main, which means your backup repository is a normal branch rather than something exotic. The commit username and commit email are left empty by default, and they are the two fields that matter for provenance, because a commit authored by nobody is harder to attribute later than one with a real identity on it.

The comment above the block points to the configuration documentation, and the file is clearly intended to be edited by hand rather than generated, since the example carries instructional comments throughout.

Storing a GitHub token in a plaintext file in the home directory of a machine that is physically on your desk is a real consideration, and the fact that the token is the first line of the file means it is the first thing to look at when setting up the repository for the first time. Whether the installer creates the file with restrictive permissions, and whether the repository excludes it from git, are questions the visible documentation does not answer.

The structure of the file also tells you what the script does with it. The values are consumed as shell variables rather than parsed, since the commit username and email are quoted empty strings, which is the syntax bash expects for a variable that is set but empty. That is consistent with a script that sources the file and uses the variables directly.

What gets backed up, and what gets left out on purpose

The backup paths are a shell array in the same file, and the commented example in the .env shows both forms it accepts:

#  backupPaths=( \
#  "printer_data/config/*" \
#  "printer_data/config/printer.cfg" \
#  )

The paths are relative to the home directory of the user running the script. The comment is explicit that script.sh starts its search in $HOME, which on a standard Klipper install is /home/{username}/, and that using the example the script will search for /home/{username}/printer_data/config/* and /home/{username}/printer_data/config/printer.cfg.

There is one rule that is easy to miss and stated clearly. When backing up a folder you should always have /* at the end of the path so that files inside the folder are properly searched. A folder path without the trailing wildcard will not pick up its contents, which is the kind of detail that produces a backup that appears to succeed and contains nothing.

The exclusion list is the other half, and it is a different kind of configuration:

exclude=( \
"*.swp" \
"*.tmp" \
"printer-[0-9]*_[0-9]*.cfg" \
"*.bak" \
"*.bkp" \
"*.csv" \
"*.zip" \
"ShakeTune_results" \
)

The comment above it says these are strings in gitignore pattern format, with a link to the git documentation for the pattern format, and that new additions must be enclosed in double quotes and follow that pattern format. So the exclusion list is applied as gitignore rules, and it is the reason the backup can be a git repository rather than a pile of files: the patterns are the same ones git already understands, so what is excluded from the commit is excluded from the repository.

The default list is a good guide to what a Klipper directory contains that you do not want in version control. Editor swap files and temporary files. The printer-specific generated configs, matched by the printer-[0-9]*_[0-9]*.cfg pattern. Backup copies with .bak and .bkp extensions. CSV files and zip archives, which is how measurement output and exported artefacts usually land in a config directory. And ShakeTune_results, which is a directory name rather than a file pattern, so the list covers both.

That list is also a description of the risk. A .csv of accelerometer or resonance data and a ShakeTune results directory are large and change on every run, so including them would make the repository grow without bound and make every commit noisy. The default exclusions are what keep the repository a record of configuration rather than a record of test data.

The repository layout, and what a small shell project still needs

The top level listing is short, and it maps onto the three stages of the script's life.

There is install.sh, the installer you run after downloading. There is script.sh, which is the script that does the work, and whose behaviour the .env comments describe. There is a utils/ directory for the helper functions, an install-files/ directory for the files the installer puts in place, and a .github/ directory for the workflows.

There is also a .env.example, which is the file discussed above, a .gitignore and a LICENSE, which is the GPL-3.0 text.

The install-files/ directory is the interesting one, because it is where the automation is actually installed rather than merely downloaded. A backup script that only runs when you remember to run it is a manual backup, and the whole value of the automated mode is that the job is registered somewhere that runs on a schedule. Putting the installed files in a dedicated directory means the script can be re-run, upgraded or removed without leaving half the state behind, and it means the repository itself stays a clean source tree rather than a mixture of source and installed artefacts.

The split of install.sh and script.sh is the other structural point, and it follows from the fact that the two run at different times. The installer runs once, on a machine you are sitting at, and it needs to be interactive because it is where the .env gets created and the GitHub side gets set up. The script runs repeatedly, unattended, on a timer, and it must not need a terminal.

The .github/ directory in the root tells you the project uses the standard GitHub workflows layout for its own continuous integration, which for a shell project of this size is likely linting and the release process rather than a test matrix.

The releases give a sense of the pace. Three releases in the last year, v1.3.4, v1.3.5 and v1.3.6, with the project still receiving pushes in October 2026, which for a utility script that runs on somebody's printer is a healthy amount of maintenance.

The community around it, and the videos that explain it

The README points at a substantial body of third-party explanation, and the range of it is informative about who uses the tool.

There are several YouTube videos about Klipper-Backup, with the thanks to everyone, and the list gives you four distinct viewpoints rather than four repetitions of the same thing. Chris Riley's video is titled Klipper Backup - Save Your Klipper Config - Before You Lose It, which is the argument for the tool stated as a warning. ModBot's is framed as This Klipper Add-on Could Save You, which is the same argument in a different voice. Minimal 3DP has a longer guide to using Klipper macros to back up configuration files, which is the alternative approach and therefore a useful comparison. And Werkplaats Marc's is in Dutch, covering Klipper backups and updates with GitHub automation, under the line Never Lose Data Again.

The existence of a macro-based alternative in that list is the most useful observation. If you already have a Klipper macro that copies your config somewhere, you have the recovery mechanism without the history. What the git approach adds is the history, and with it the ability to see what changed between the working version and the broken one.

The Minimal 3DP video is also a technical hint, because a macro that runs inside Klipper is a different thing from a script that runs on the operating system. A macro can capture a snapshot at a moment you choose, before a specific change, whereas the scheduled script captures on a timer. Neither is strictly better; they cover different moments.

What is missing from the README, and this is a real gap for an English-speaking reader, is any explanation of how the tool works beyond the two installation commands. The docs site is referenced and the author recommends reading them, and the configuration page is linked from the .env file, but the repository itself is a short document. For a project with a whole ecosystem around it, from fluidd and mainsail to moonraker and octoprint, that is a deliberate choice to keep the README focused, and it means the interesting detail lives in the documentationation rather than in the repository.

Editorial conclusion

Adopt Klipper-Backup if you run Klipper on a printer and have lost a working configuration before, because the failure it prevents is a bricked printer with no record of what used to work. Do not adopt it expecting a general backup tool, since it is built specifically around Klipper config directories and a git repository. Before you let it run unattended, check the exclude list in your .env, because the default patterns skip printer-specific generated configs and the format of the list is gitignore syntax, and note that the restore function is still in open beta.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. Staubgeborener/Klipper-Backup on GitHub