klipper_z_calibration: a Klipper plugin that measures the Z offset for you

Baby stepping, but automatic and before every print

The pitch in the README is a single comparison, and it is a good one. The plugin is like automatically baby-stepping on your 3D printer before every print, and the first layer will always be perfect, no matter which nozzle or new flex-plate is being tested.

That framing tells you the whole scope. It is not a mesh leveler and it is not a probe implementation. It is a Z offset measurement that runs as part of the print sequence, so the first layer is laid down at a known distance from the bed, and the value it finds is written into the machine's switch-offset setting.

The audience is therefore a Klipper operator who already understands Z offset, endstops and the difference between a probe and a manual measurement, and who wants that step to stop being a manual ritual. The topics on the repository, 3d-printing, klipper and vorondesign, place it in the Voron design community in particular, where flex plates and tool changers make the Z offset something that changes often.

The behaviour is deliberate rather than incidental. The whole point is that the measurement happens before the print rather than when the filament is changed, which means the first layer is not the experiment any more. What was a two minute paper test becomes a step in the start-up sequence.

The project is GPL-3.0 licensed, the default branch is master, and the last push was on 2026-10-05.

The switch-offset sign convention is the thing to get right

There is one line in the README that any user needs, and it is the line everybody misreads on the first attempt.

The tip says: the smaller the switch-offset, the further the nozzle is away from the bed.

That is a sign convention, and it is the opposite of what many people expect. The switch-offset is the value that tells the firmware how far below, or above, the nozzle currently sits relative to the zero reference position, so a smaller number means the nozzle is higher above the bed, and a larger number means it is closer. If you assume the other direction, the plugin will appear to make the offset worse, and the first print will show it.

Two of the recent release notes are about exactly this class of problem, and they are worth reading as a pair. v1.1.1 revised messages, v1.1.2 fixed reading the zero reference position, and v1.1.3 fixed reading the z-endstop.

Both of the later fixes are about how the plugin interprets the machine's own state, not about the measurement itself. A Z offset is only meaningful relative to a known zero, so if the plugin reads the zero reference position or the endstop position incorrectly, the number it computes is wrong even when the measurement is sound. The fix history is a good indication of where the sharp edges are.

The release dates are 2024-07-30, 2024-08-01 and 2025-05-07, and there is no release newer than v1.1.3 in the tag list, so the repository is being worked on, with the last push on 2026-10-05, but the published versions are not moving quickly.

One Python file and a shell script

The repository is very small, and that is worth noting before anyone wonders where the configuration lives.

The top level entries are z_calibration.py, which is the plugin itself, install.sh, the LICENSE file, a pictures/ directory with the images the README uses, the README, and a .github/ directory with the workflows. There is no settings file in the tree, no example configuration directory and no separate library.

That tells you the model. This is a Klipper extension, not an application, and Klipper's own configuration model is the configuration. The plugin is loaded from the printer configuration and the settings it needs, such as the endstop and the zero reference it reads, are the ones the printer already has.

The consequence for a reader is that the repository is not where you will learn how to use it. The README says to visit the wiki to view the full documentation for this Klipper plugin, and it points separately at the release notes, which are also in the wiki, at a Changelog page.

So the documentation lives in the wiki and the code is a single file, and an evaluation consists of reading the wiki page and looking at how few lines the plugin is. That combination is unusual in a good way: a Klipper extension that can be read end to end in one sitting is a much better thing to trust than a large configuration framework.

The wiki, the changelog and the video

The documentation arrangement is worth spelling out because it is the difference between a project you can evaluate and one you cannot.

The wiki holds the full documentation, and the release notes are on a Changelog page inside the same wiki rather than in the repository. There is a separate repository with an image of the logo, a set of badges for releases, stars, forks and the licence, and a downloads link pointing at the releases page.

For a visual aid there is a how-to video by Kapman, linked from the README, which for a calibration procedure is arguably the most useful form the documentation can take, because the failure mode of a Z offset mistake is something you see rather than something you read.

And there is a note in the README that says: the smaller the switch-offset, the further the nozzle is away from the bed. It is set as a pushpin callout, which is a small signal about how often people get it wrong.

The project is also supported through a ko-fi link, which is a common arrangement for a single maintainer who writes firmware-adjacent tools for a hardware community, and the README closes with a thanks for the feedback and support.

The RRF version, and what it changes

The README points at an alternative implementation, and the comparison is worth making because it is not simply a fork.

Under the heading about looking for an RRF version of this automatic z-offset calibration, the link goes to a repository called Auto-Z-calibration-for-RRF-3.3-or-later-and-Klicky-Probe, by pRINTERnOODLE. The author calls it really fantastic to see.

The difference in approach is in the target rather than in the idea. This plugin is a Klipper extension, and the alternative is built for RRF, Recore Firmware, and specifically for RRF 3.3 or later, and it names a Klicky probe in its title. The measurement problem is the same, but the firmware underneath is a different one with different concepts for stepper positioning, endstops and offsets, so the implementations cannot be shared.

That is a useful boundary for an evaluation, because it tells you the plugin is not a generic 3D printer feature that any firmware can run. It is written against one firmware's model of the machine, and the alternative is written against another's. If you are on Klipper, this is the relevant one; if you are on RRF 3.3 or later, the other repository is the one to read, and the fact that it exists at all is a good sign that the problem is well understood by the community rather than being one maintainer's private workaround.

The disclaimer, and when to leave it alone

The last section of the README is a disclaimer, and its wording is worth taking seriously rather than reading as boilerplate.

It says: you use it at your own risk, the author is not responsible for any damage that might result. Then the qualification: although this extension works rock solid for the author and many others for years now, always be careful and double check everything when configuring or working with your printer, and as always, never leave unattended while printing.

That is a careful piece of risk statement, and it tells you what the failure mode is. A Z offset plugin moves the nozzle relative to the bed as part of starting a print, and if the sign convention is inverted, or the endstop reading is wrong, the first layer is laid down at the wrong height. On most printers that is a ruined print. On a machine where the nozzle can reach the bed, it is a crash, and on a printer with an open frame it is a crash into something that was not supposed to be there.

So the reasonable adoption path is the one the author describes. Understand your printer's Z behaviour, watch the first measurement happen, and confirm by hand that the resulting offset is the one you would have set. Only then let it run unattended, and only then leave the printer alone with it.

The plugin is a convenience that automates a judgement, and the judgement is still yours on the first run. The last push on 2026-10-05 and the release history through v1.1.3 suggest it is still being cared for, but the README asks for care in return, and that is the correct way to read the project.

Editorial conclusion

Adopt klipper_z_calibration if you run Klipper on a printer whose Z offset drifts with the nozzle or build plate, and if you want the measurement repeated automatically rather than by hand. Do not adopt it if you are on a firmware other than Klipper, since the plugin is Klipper specific, and do not treat it as a substitute for understanding your printer's Z axis. Verify first the sign convention, because the README states that the smaller the switch-offset the further the nozzle is away from the bed, and check your own configuration by hand once before you let the plugin move the nozzle on its own.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. protoloft/klipper_z_calibration on GitHub
4. README
5. Releases