How to add a purge line macro in Klipper

Put the purge in its own [gcode_macro PURGE_LINE] and call it as the last line of your start macro, once M109 has the nozzle at temperature. The macro below draws one 100 mm line at 0.3 mm along the front of the bed and works out the extrusion amount itself.

How do you add a purge line to a Klipper start macro?

Write a separate PURGE_LINE macro and call it as the final line of PRINT_START, after the bed mesh and after M109 finishes heating the nozzle. Inside it, wrap the moves in SAVE_GCODE_STATE and RESTORE_GCODE_STATE, switch to relative extrusion with M83, then draw one line along a clear strip of the bed.

Klipper’s G-code reference lists no purge command, so the line is plain G1 moves. As a separate macro, it also runs from the console, which lets you tune it without starting a print.

How to add a purge line macro in Klipper

1. Pick the strip. Find a band near the front edge that no print uses, inside position_min and position_max of your [stepper_x] and [stepper_y] sections.
2. Add the macro. Paste the PURGE_LINE macro below into printer.cfg, or into a file it pulls in with [include].
3. Set the coordinates. Change the X and Y defaults to the start of your strip. The line runs LENGTH mm toward +X, and the nozzle travels 10 mm past its end.
4. Call it last. Add PURGE_LINE as the final line of PRINT_START, below M109.
5. Remove the slicer’s purge. Delete any intro line left in the slicer’s start G-code, or the printer purges twice.
6. Restart and test. Send RESTART, home, heat the nozzle and run PURGE_LINE from the console. Adjust HEIGHT until the line lies flat.

Klipper purge line macro example

[gcode_macro PURGE_LINE]
description: Prime the nozzle with a line along the front of the bed
gcode:
    {% set x0 = params.X|default(10)|float %}           ; placeholder: start of your clear strip
    {% set y0 = params.Y|default(5)|float %}            ; placeholder: front edge, inside travel
    {% set length = params.LENGTH|default(100)|float %}
    {% set height = params.HEIGHT|default(0.3)|float %}
    {% set width = params.WIDTH|default(0.8)|float %}
    {% set dia = printer.configfile.settings.extruder.filament_diameter|float %}
    {% set e = length * height * width / (3.14159 * (dia / 2) ** 2) %}
    SAVE_GCODE_STATE NAME=purge_line
    G90                                     ; absolute moves
    M83                                     ; relative extrusion
    G1 Z5 F3000                             ; lift before travelling
    G1 X{x0} Y{y0} F6000                    ; go to the start of the line
    G1 Z{height} F600                       ; drop to purge height
    G1 X{x0 + length} E{e|round(2)} F1200   ; draw the line at 20 mm/s
    G1 X{x0 + length + 10} F6000            ; fast move off the end breaks the string
    G1 Z2 F600                              ; lift clear
    RESTORE_GCODE_STATE NAME=purge_line

What the lines do:

• The e formula divides the line’s volume (length × height × width) by the filament’s cross-section. It reads filament_diameter from [extruder] through printer.configfile.settings. With the defaults and 1.75 mm filament, it pushes about 10 mm of filament.
• SAVE_GCODE_STATE and RESTORE_GCODE_STATE put back the coordinate mode, the M83/M82 mode and the E position, so a slicer file using absolute extrusion carries on where it expects. Without MOVE=1, the toolhead stays where the purge ended.
• G90 and M83 give absolute moves with relative extrusion. Klipper’s command templates page advises to “always explicitly set the G-Code parsing state prior to issuing a G1 command.”

Klipper’s config parser strips inline comments starting with ;, so the comments on the {% set %} lines are safe. Override any default from the call, as in PURGE_LINE Y=3 LENGTH=60 (see macro parameters).

Where the purge line goes in a Klipper start print macro

The purge comes last: after the bed heats, after homing and meshing, and after the nozzle reaches temperature. Purge before the mesh and the nozzle oozes again while it probes.

[gcode_macro PRINT_START]
gcode:
    {% set BED_TEMP = params.BED_TEMP|default(60)|float %}
    {% set EXTRUDER_TEMP = params.EXTRUDER_TEMP|default(200)|float %}
    M190 S{BED_TEMP}
    G28
    BED_MESH_CALIBRATE ADAPTIVE=1
    M109 S{EXTRUDER_TEMP}
    PURGE_LINE                              ; last line: prime right before the print

Each step of that macro is explained on the PRINT_START macro page.

Klipper prime nozzle macro without a line

To prime in place, over a purge bucket or a clear corner, extrude without moving in X or Y. Klipper calls that an extrude-only move: max_extrude_only_distance caps each one at 50 mm of filament by default, and max_extrude_only_velocity caps its speed.

[gcode_macro PRIME_NOZZLE]
description: Extrude in place to prime the nozzle
gcode:
    {% set amount = params.E|default(15)|float %}   ; mm of filament, keep under 50
    SAVE_GCODE_STATE NAME=prime_nozzle
    G90
    M83
    G1 Z5 F3000
    G1 X5 Y5 F6000                          ; placeholder: over your bucket or a clear corner
    G1 E{amount} F150                       ; extrude in place at 2.5 mm/s of filament
    G1 Z10 F600                             ; lift away from the blob
    RESTORE_GCODE_STATE NAME=prime_nozzle

A blob left hanging from the nozzle lands on the print, so follow the prime with a brush wipe.

Adaptive purge line next to the print (KAMP)

The LINE_PURGE macro from KAMP (Klipper Adaptive Meshing and Purging) draws the line beside the objects you are printing, purge_margin (default 10 mm) in front of them, instead of at a fixed spot. Its other defaults are purge_amount: 30 mm of filament, purge_height: 0.8 mm and flow_rate: 12 mm³/s.

KAMP’s README says “it is required to add max_extrude_cross_section: 5” to [extruder]; without it, the macro skips the purge with a warning. It finds the objects through [exclude_object], the same setup as an adaptive bed mesh. Mainline Klipper now meshes adaptively by itself, so you need only the purge. Add [include KAMP_Settings.cfg] to printer.cfg, uncomment the Line_Purge.cfg include in that file and call LINE_PURGE at the end of PRINT_START.

Klipper purge line errors and fixes

Console message	Cause	Fix
Extrude below minimum temp	Nozzle below min_extrude_temp (170 °C by default)	Call PURGE_LINE after M109, not M104
Move exceeds maximum extrusion (… vs …)	Height × width over max_extrude_cross_section (default 4.0 × nozzle diameter², 0.64 mm² for a 0.4 mm nozzle)	Lower HEIGHT or WIDTH, or raise the setting
Extrude only move too long	In-place prime over max_extrude_only_distance (50 mm by default)	Split it into two moves
Must home axis first	No G28 before the purge	Home earlier in PRINT_START
Move out of range	Strip outside position_min/position_max	Bring X, Y or LENGTH inside the limits

A thin, broken line means the nozzle sits too close: raise HEIGHT or check your Z offset. A round bead that barely sticks means it sits too high. If only the first few millimetres come out thin, the filament is still pulled back by the last print’s final retract. KAMP fixes this with tip_distance, an extrusion before the line set “a little bit less than the final retract” in your end macro. A G1 E move of that length just before the line does the same.