How to Level a Bed With BLTouch: Marlin and Klipper Guide

Learning how to level a bed with BLTouch means separating two jobs that get conflated constantly: mesh bed leveling, which maps the bed’s physical imperfections, and Z-offset calibration, which tells the printer exactly how far the nozzle sits from where the probe triggers. Get the mesh right and skip the offset and you’ll still crash the nozzle into glass or print half a millimeter above the bed. Both steps matter, and they’re not the same step.

This guide covers both firmwares. Marlin and Klipper use different commands, opposite sign conventions on the Z-offset, and each has its own way of building a perfect mesh that then never gets applied to a print. The sequence below is the same in both: verify the probe, tram by hand, build the mesh, set the offset, prove it with a test print.

What the BLTouch Actually Measures

A BLTouch is a mechanical probe. A solenoid pushes a metal pin down, the pin contacts the bed, a Hall-effect sensor inside the body registers the moment that contact pushes the pin back up, and the probe then retracts the pin. During a bed leveling routine the firmware moves this probe to a grid of points across the bed and records the trigger height at each one. That data becomes a mesh — a 3D map of every dip, bow, and high spot on your bed surface, which Marlin then uses to adjust Z height on the fly as the nozzle moves (Marlin Firmware, Automatic Bed Leveling).

What the mesh does not tell you is where your nozzle tip actually is relative to that same surface, because the probe pin and the nozzle are two different points in space, offset by several millimeters. That gap is the Z-offset, and it has to be set separately from the mesh.

Verify the Probe Before You Trust It

A BLTouch that deploys but never reports a trigger will drive the nozzle straight into the bed on the first homing move. Two minutes of verification is what stands between a working setup and a cracked glass sheet, which is why the Klipper BL-Touch docs put a manual check sequence ahead of any probing.

On Klipper, run the checks in this order:

BLTOUCH_DEBUG COMMAND=pin_down, then pin_up. The pin should physically move and the LED should follow.
With the pin deployed, run QUERY_PROBE and confirm it reports probe: open. Push the pin up by hand and confirm it flips to probe: TRIGGERED.
Run G28 and, as Z descends, touch the pin with a fingernail. Motion must stop instantly.

If step 2 never changes state, suspect the wiring before the probe. Klipper needs a pull-up on the sensor pin, written as a ^ prefix (sensor_pin: ^PC14); a missing ^ or a swapped sensor and control wire accounts for most “dead probe” reports. Marlin users can do the equivalent check with M119 after deploying the pin, watching the z_min endstop state change.

The unit also self-tests at power-up and before each probing cycle. A pin that cycles and then flashes an alarm has failed that test — usually a bent pin, a bad crimp, or a marginal 5 V rail, since per ANTCLABS the sensor draws under 15 mA at standby but up to 300 mA while moving the pin. That alarm is a feature: it fails closed instead of quietly feeding bad numbers into the mesh.

Mechanical Tramming Comes First

Run bed leveling before you’ve trammed the bed by hand and you’re just measuring a bad starting position more precisely. A BLTouch mesh compensates for minor waviness across the print area — it is not a substitute for getting the bed roughly parallel to the X gantry. The split between what tramming fixes and what a probe fixes is set out in bed leveling manual vs auto. Snug the bed’s leveling knobs or springs by eye and by the classic paper-drag test at the four corners and center before you ever run an automated probe cycle. If the corners are wildly different heights, fix that mechanically first; asking the mesh to correct for a badly tilted bed pushes the compensation to its limits and eats into usable Z range.

Tram hot, not cold. Aluminium beds grow measurably as they heat, so bring the bed to your normal print temperature (60 °C for PLA) and let it soak before the paper-drag pass. Five minutes of tramming is the difference between a mesh with a 0.1 mm range and a mesh spending its whole correction budget fighting a 1 mm wedge.

A perfect mesh will still give a poor first layer if the extrusion feeding it is wrong, so run e-step calibration before blaming the probe for a squashed or starved bottom layer.

Wiring and Firmware Basics

BLTouch uses five wires: power, ground, a control/PWM signal, and a separate signal wire that reports the Z-stop trigger. Most current mainboards have a dedicated BLTouch header that maps these correctly, but on some boards — Antclabs specifically calls out Melzi, Ender-3, and certain ANET boards — a large capacitor in the end-stop input circuit interferes with the fast trigger signal and needs to be removed or bypassed for reliable operation (ANTCLABS manual archive). Check your board’s BLTouch wiring notes before you assume a bad probe is a bad sensor.

In Marlin, enabling the probe means uncommenting BLTOUCH in Configuration.h, setting NOZZLE_TO_PROBE_OFFSET to your measured X/Y offset (Z gets tuned live, covered below), and picking a leveling method — bilinear or unified bed leveling are the common choices. If you’re running pre-built firmware from your board vendor, this is usually already compiled in and exposed through the LCD menu instead.

In Klipper the same job is config rather than a recompile. printer.cfg needs a [bltouch] section with sensor_pin (with the ^ pull-up) and control_pin, endstop_pin: probe:z_virtual_endstop in [stepper_z] so the probe becomes the Z endstop, and a [safe_z_home] block so homing happens over the bed rather than off the front-left corner where the probe has nothing to touch.

Running the Mesh (Marlin: G29)

With the probe wired and firmware flashed, home all axes and run:

G28
G29
M500

G28 homes the printer, G29 runs the probing routine and builds the mesh, and M500 writes it to EEPROM so it survives a power cycle. Depending on which bed leveling system is compiled in, G29 will probe anywhere from a 3x3 to a much denser grid. Marlin also supports a fade height, which tapers the correction down to zero above a set Z so the mesh only affects the first several layers rather than warping tall prints (Marlin Firmware, Automatic Bed Leveling).

Running the Mesh (Klipper: BED_MESH_CALIBRATE)

Klipper’s [bed_mesh] section defines the probing area and density. Per the Klipper Bed Mesh docs the minimum is 3 points per axis, and the documented example uses probe_count: 5, 3 on a 250 x 220 mm bed for 15 points. On a typical 220 x 220 mm bed, probe_count: 5, 5 (25 points) is a sensible density; going denser mostly buys probing time unless the surface is genuinely warped.

Build and store it with:

BED_MESH_CALIBRATE
BED_MESH_PROFILE SAVE=default
SAVE_CONFIG

The Trap: A Saved Mesh That Never Loads

This is the failure that produces a textbook calibration and a terrible first layer, and it exists in both firmwares in slightly different shapes.

On Klipper, current versions do not load the default mesh profile automatically at startup. The docs are explicit that you have to call BED_MESH_PROFILE LOAD=default yourself, normally inside your PRINT_START macro right after G28. Skip it and every print runs with zero compensation while the saved mesh sits on disk unused. It is the single most common reason a fresh BLTouch install appears to change nothing at all.

On Marlin, G29 builds the mesh and M500 stores it, but bed leveling still has to be switched back on after each home. Add M420 S1 to your start G-code after G28 — or set ENABLE_LEVELING_AFTER_G28 in firmware — or the stored mesh is loaded and then ignored.

Setting the Z-Offset

This is the step that actually determines first-layer squish, and it’s where most BLTouch setups go wrong. The offset is the vertical distance between where the probe triggers and where the nozzle tip touches the bed — set with M851:

M851 Z-2.50
M500

Negative because the probe pin, mounted below and behind the nozzle, triggers before the nozzle would reach the bed. The exact value depends entirely on your mount geometry, so there’s no universal number to copy — you tune it live.

The practical method: home the printer so the probe centers itself and sets Z=0, then move the nozzle down toward the bed in small increments (0.05–0.1 mm steps) with a piece of standard printer paper underneath. Stop when the paper drags with light, consistent resistance — the same feel used for manual corner leveling. If BABYSTEP_ZPROBE_OFFSET is enabled, you can do this live during the first layer of an actual print and save the result directly, which is faster than guessing and re-homing repeatedly (Teaching Tech calibration guide). Whatever value you land on, run M500 to commit it to EEPROM — an offset that isn’t saved disappears on the next reboot.

The Klipper Equivalent, and Its Opposite Sign

Klipper defines z_offset as the distance above the nozzle tip at which the probe triggers, so it is a positive number where Marlin’s M851 Z is negative. Copying a Marlin value across firmwares, sign included, is a reliable way to bury the nozzle. The Klipper docs suggest sanity-checking that the result lands near 1 mm: far enough that the probe fires before the nozzle arrives, retracted enough to clear printed parts.

With the bed at print temperature:

G28, then PROBE_CALIBRATE. Klipper probes once and parks the nozzle over that same point.
Slide plain printer paper (roughly 0.1 mm) under the nozzle and step down with TESTZ Z=-0.1, dropping to TESTZ Z=-0.05 as the drag comes up.
When the paper drags with light, even resistance, run ACCEPT, then SAVE_CONFIG. Klipper writes the value into printer.cfg and restarts.

A Concrete Example: Ender-3-Class Printer, 0.4 mm Nozzle, PLA

On a Creality-style printer with a bracket-mounted BLTouch and stock 0.4 mm nozzle, a first-layer height of 0.2 mm with PLA at a moderate bed temperature is a reasonable starting profile once the mesh and offset are both set. Print a single-layer first-layer test square or calibration cube and check it at all four corners plus the center, not just the middle. Because the mesh is already compensating for bed variance, corner-to-corner consistency after leveling is the actual signal you’re checking, not an absolute number.

Verifying It Worked

Print a first-layer test pattern — five 25 mm squares, one per corner plus centre, is the most informative version — at 0.2 mm layer height, your normal material settings (200 °C nozzle and 60 °C bed for PLA), and 20–30 mm/s on the first layer. Success looks like: a slightly flattened, evenly squished line with no visible gaps between adjacent lines and no scraping or dragging by the nozzle. If lines are too flat and translucent, the nozzle is too close. If lines are round and don’t adhere or separate under light finger pressure, the nozzle is too far. Adjust in 0.02–0.05 mm increments and reprint the test rather than committing a full print to the guess.

The five-square layout separates the two variables. All five squares matching each other is the mesh working; the overall squish level across all of them is the Z-offset. One bad corner points at the mesh or at tramming, uniform bad squish points at the offset.

If squares vary run to run rather than corner to corner, the problem is repeatability, not calibration. ANTCLABS rates the BLTouch at a standard deviation around 0.005 mm while conceding that real installs on flexible machines land anywhere from 0.001 to 0.05 mm — a loose bracket or a wobbly gantry swamps the sensor’s own precision. Marlin can measure this directly with the M48 probe repeatability test: ten probes with a standard deviation above roughly 0.01 mm points at the mount, the wiring, or a counterfeit unit (genuine boards carry a QR code on the PCB per ANTCLABS) rather than at anything you did during setup.

When the Offset Drifts

BLTouch offsets aren’t permanent. Bed thermal expansion, a probe bracket that’s slightly loose, or a nozzle swap all shift the real-world distance the offset is supposed to represent, and the printer keeps using the old number with total confidence. The failure shows up as a gradually worse first layer over weeks rather than a sudden crash, so the fix is a scheduled re-check against a known-good baseline instead of a reaction to a ruined print. Recalibrate the Z-offset any time you change nozzles, swap the print surface, or re-seat the BLTouch bracket, and treat drift as a maintenance checklist item rather than a one-time setup step. If the surface itself changed, the bed surface reference covers how much each material shifts the probe’s reading.

The bracket geometry is the offset. Touch the bracket and the stored number is stale, whichever firmware holds it.

With the mesh and Z-offset settled, the machine is ready for the extrusion side of tuning. The next stage is extruder e-steps calibration, and the sequence after that — drying, temperature, flow ratio, pressure advance, retraction — is laid out with its dependencies in the 3D printer calibration order. Doing probe work last, after those, means redoing them: the Z-offset changes the first layer, and the first layer is what every subsequent test print is measured on. For the conceptual background on what ABL is and is not solving, see bed levelling explained: manual vs auto.