Klipper rotation distance calculator for extruders and axes

The formula

Klipper’s rotation_distance is the distance in millimeters that an axis, or the filament, moves during one full turn of the stepper motor. When gear_ratio is set, it is the distance per turn of the final gear instead.

From a steps per mm (e-steps) figure:

rotation_distance = full_steps_per_rotation × microsteps × gear / steps_per_mm

From the hardware:

belt axis:   rotation_distance = belt_pitch × pulley_teeth
lead screw:  rotation_distance = thread_pitch × thread_starts
extruder:    rotation_distance = drive_gear_diameter × π

From a test extrusion (Klipper’s measure and trim):

new rotation_distance = previous × actual_extruded / requested_extruded

full_steps_per_rotation is 200 for a 1.8° motor and 400 for a 0.9° motor. gear is 1 with no gear_ratio line; gear_ratio: 50:10 makes it 5. The calculator also turns the result back into steps per mm with the same terms, the way Klipper does internally.

How do you calculate rotation distance in Klipper?

Measure how far one motor turn moves the axis or the filament. On a belt axis that is belt pitch times pulley teeth, on a lead screw thread pitch times starts, and on an extruder drive gear diameter times π. A 2 mm pitch belt on a 20-tooth pulley gives rotation_distance: 40, the worked example in Klipper’s own docs.

Typical hardware results:

Hardware	Working	rotation_distance
2 mm belt, 20-tooth pulley	2 × 20	40
T8 lead screw, 2 mm pitch, 4 starts	2 × 4	8
M8 threaded rod	1.25 × 1	1.25
Voron 2.4 Z belt drive	40, with gear_ratio: 80:16	40

The Voron 2.4 Z line shows how a reduction works. Its Z motors drive a 16-tooth pulley that turns an 80-tooth pulley, so the config keeps rotation_distance: 40 for the final pulley and adds gear_ratio: 80:16.

An extruder from the hardware is only a first guess. The grip of the drive gear varies between printers and even between spools, so Klipper’s docs say to start from the gear diameter or a published value and then trim it with a test extrusion (below). X, Y and Z are the exception: Klipper advises against measure and trim on motion axes, because a measured move is less accurate than the belt and screw figures.

Paste the result under the stepper’s section in printer.cfg and send RESTART.

How do you convert e-steps to rotation distance?

Multiply full steps per rotation by microsteps, then divide by the steps per mm. For a 1.8° motor at 16 microsteps that is 200 × 16 ÷ steps per mm. Bondtech’s BMG figure of 415 e-steps gives 3,200 ÷ 415 = 7.711. Use 400 for a 0.9° motor, and use the microsteps the e-steps were set at.

Worked example: a BMG from 415 e-steps

These are the calculator’s defaults.

1. Steps per motor turn: 200 full steps × 16 microsteps = 3,200.
2. rotation_distance: 3,200 ÷ 415 = 7.711 mm of filament per motor turn.
3. Config lines: rotation_distance: 7.711 and microsteps: 16 under [extruder].

Bondtech publishes the same conversion and rounds it to 7.71. The Voron configs describe the same gearing a second way: rotation_distance: 22.6789511 with gear_ratio: 50:17. Both work out to 415 steps per mm at 16 microsteps, because 22.6789511 × 17 ÷ 50 = 7.711.

Some common Marlin values convert like this at 200 full steps and 16 microsteps:

Steps per mm	Hardware it matches	rotation_distance
80	2 mm belt, 20-tooth pulley	40
400	T8 lead screw	8
415	Bondtech BMG extruder	7.711

If the e-steps were set at 32 microsteps, the figure is twice as large and the result is the same: 6,400 ÷ 830 = 7.711. The microstep count changes steps per mm, never rotation_distance, so a Klipper config can change microsteps and leave rotation_distance alone. If you are unsure of the microsteps, Klipper’s docs say to use 16.

For X, Y and Z, Klipper’s docs expect a whole number. If the conversion lands within 0.01 of one, round to it; the calculator does this when you pick an axis. To go the other way, from a Klipper value back to Marlin’s M92, use the e-steps calculator.

What rotation distance does a Z axis lead screw need?

A T8 lead screw, the common 8 mm Z screw, needs rotation_distance: 8. It has a 2 mm thread pitch and 4 separate threads, so one motor turn moves the nut 2 × 4 = 8 mm. Other screws follow the same rule, pitch times starts: a single-start TR8x2 needs 2 and an M8 threaded rod needs 1.25.

Screw	Pitch (mm)	Starts	rotation_distance	Steps per mm at 16 microsteps
T8 / TR8x8	2	4	8	400
TR8x4	2	2	4	800
TR8x2	2	1	2	1,600
M8 threaded rod	1.25	1	1.25	2,560
M6 threaded rod	1	1	1	3,200

The lead (travel per turn) counts, not the thread spacing. A T8 screw with 4 starts looks like a 2 mm thread but travels 8 mm per turn. To tell the types apart, count the thread starts at the end of the screw, or mark the nut and turn the screw once by hand.

Put the value under [stepper_z], and under [stepper_z1] and onward if the printer has more Z motors. With a T8 screw, 200 full steps and 16 microsteps, one microstep moves Z by 8 ÷ 3,200 = 0.0025 mm (2.5 µm).

Setting gear_ratio

Use gear_ratio when a gearbox or a belt reduction sits between the motor and the part that moves. Write it as driven teeth to driving teeth. With it set, rotation_distance is the travel per turn of the final gear, and Klipper multiplies steps by the ratio.

• Voron Stealthburner or Clockwork 2: gear_ratio: 50:10.
• Bondtech BMG gears, sold as 3:1: gear_ratio: 50:17.
• A “5.18:1” planetary gearbox: gear_ratio: 57:11.
• Two stages, such as a 5:1 gearbox driving a 16-tooth to 80-tooth belt: gear_ratio: 5:1, 80:16.

The ratio changes steps per mm, not the travel per final turn. A Stealthburner at 16 microsteps runs 200 × 16 × 5 ÷ 22.6789511 = 705.50 steps per mm. Leave gear_ratio out if you take an extruder’s single combined value, such as Bondtech’s 7.71 for the BMG. Setting both would apply the gearing twice.

Calibrating an extruder with measure and trim

Start from a converted or published value, then measure how far the extruder pushes filament.

1. Heat the hotend to printing temperature with filament loaded.
2. Mark the filament about 70 mm above the extruder intake and measure that distance with calipers.
3. Send G91, then G1 E50 F60. The slow rate matters: a fast push builds pressure and skews the result. The move takes about 50 seconds.
4. Measure the mark again. Actual extruded = first distance − second distance.
5. New rotation_distance = previous × actual ÷ 50. Round it to three decimals.

Worked example: a Stealthburner that under-extrudes

Previous value 22.6789511. The mark sat 70 mm from the intake and 21 mm after the move, so the extruder pushed 49 mm of the 50 asked.

new rotation_distance = 22.6789511 × 49 / 50 = 22.225

The value went down. A smaller rotation_distance means less filament per motor turn, so Klipper turns the motor further for each commanded millimeter. That makes up the missing filament. This is the opposite of Marlin, where an under-extruding extruder needs more e-steps. The gear_ratio: 50:10 line stays as it was.

Test the value without a restart using SET_EXTRUDER_ROTATION_DISTANCE EXTRUDER=extruder DISTANCE=22.225. It is lost on the next reset, so write it into printer.cfg and send RESTART. If the result was more than about 2 mm off, run the test again with the new value. Once the extruder is trimmed, a flow test tunes the slicer side; the flow rate calculator handles that.

Extruder starting values, with sources

Each value is the one its maker or reference config publishes. Steps per mm is worked out at 200 full steps and 16 microsteps.

Extruder	rotation_distance	gear_ratio	Steps per mm	Source
Voron Stealthburner / Clockwork 2	22.6789511	50:10	705.50	Voron 2.4 printer.cfg
Voron Afterburner / Clockwork (BMG gears)	22.6789511	50:17	415.00	Voron 2.4 printer.cfg
Bondtech BMG	7.71	none	415.05	Bondtech BMG page
Bondtech LGX Lite	5.7	none	561.40	Bondtech LGX Lite page
Orbiter 2.0	4.69	none	682.30	Orbiter v2.0 page
Creality Ender 3 V2 stock extruder	34.406	none	93.01	Klipper’s Ender 3 V2 config

Two of these makers publish an e-steps figure as well, and it does not match exactly. Bondtech lists 562 e-steps for the LGX Lite, which converts to 5.694, rounded on the page to 5.7. The Orbiter v2.0 page lists 690 steps per mm at 16 microsteps, which converts to 4.638, next to a Klipper value of 4.69. Either is only a start, so trim the value on your printer.

For an extruder not listed, measure the drive gear’s diameter where its teeth grip the filament and multiply by π. If the extruder is geared, add its gear_ratio.