What Klipper macros can do

Klipper macros can automate anything you could type into the console. They heat, home, mesh and purge before a print, then park and shut down after it. They also pause for a filament change, wipe the nozzle, skip a failed part and ask you a question on screen. Each macro is a named command in your config that the slicer, the console or another macro calls.

What are Klipper macros?

A Klipper macro is a named G-code command you define yourself in a [gcode_macro] section of printer.cfg. Calling its name runs the commands listed under gcode:. Those commands are a Jinja2 template, so a macro can take parameters, read the printer’s live state, branch with if and loop with for.

[gcode_macro PARK]
description: Lift the nozzle and move to the back corner
gcode:
    {% set z = params.Z|default(10)|float %}
    SAVE_GCODE_STATE NAME=park_state
    G91
    G1 Z{z} F600
    G90
    G1 X200 Y200 F6000          ; placeholder: a safe spot inside your bed
    RESTORE_GCODE_STATE NAME=park_state

Type PARK or PARK Z=30 in the console and it runs. A [gcode_macro] section takes four options, per Klipper’s configuration reference:

• gcode: holds the commands. It is the only required option.
• description: is the text shown by HELP and autocomplete. It defaults to “G-Code macro”.
• variable_<name>: stores a value the macro can read and change at run time. See macro variables.
• rename_existing: lets a macro replace a built-in command and keep the original under a new name. See rename_existing.

Names are case-insensitive, and any digits must come at the end of the name: Klipper accepts TEST_MACRO25 but rejects MACRO25_TEST3. To add the section to your config and reload it, follow adding macros to Klipper.

How Klipper runs a macro

Klipper’s command templates page states that “macros are first evaluated in entirety and only then are the resulting commands executed.” A value the macro reads from printer is the value from before any of its own commands ran. A macro that heats the bed and then checks printer.heater_bed.temperature sees the old temperature. To act after something finishes, use a wait command or a second macro. Making a macro wait covers both.

What a Klipper macro can use

Klipper’s command templates page lists what a macro template can work with:

• Parameters. params.NAME reads values passed on the call line. Klipper passes them “always in upper-case” and “always passed as strings”, so convert with |int or |float. See macro parameters.
• Printer state. printer.<section> reads live status, such as printer.extruder.temperature or printer.toolhead.homed_axes.
• Logic. Jinja2 {% if %} and {% for %} blocks choose and repeat commands. See if, else and loops.
• Actions. action_respond_info() prints a message to the console. action_raise_error() stops the macro and any macro that called it.
• Saved values. With [save_variables] enabled, SAVE_VARIABLE writes a value to disk that survives a restart.
• Timers. A [delayed_gcode] section runs G-code after a delay or at startup. See running a macro on startup.

Which macros does Klipper include by default?

None. Klipper loads no macros of its own, so there is no default PRINT_START, END_PRINT or M600. Enabling [pause_resume] adds built-in PAUSE, RESUME, CLEAR_PAUSE and CANCEL_PRINT commands, but they do not park, retract or turn off heaters. The macros in Mainsail’s or Fluidd’s config file add that.

What Klipper’s own commands do

Klipper’s G-Codes reference lists the four [pause_resume] commands, and its source (pause_resume.py) shows what each does. PAUSE stops the print and saves the G-code state. RESUME moves back to the saved position at recover_velocity (default 50 mm/s) and continues. CANCEL_PRINT closes the file and clears the pause.

The rest of Klipper’s built-in commands, such as TURN_OFF_HEATERS, SAVE_GCODE_STATE and TEMPERATURE_WAIT, are the building blocks for macros.

Klipper does ship example macros in config/sample-macros.cfg: START_PRINT, END_PRINT, M600, M300 (beeper), M486 (cancel object) and M117, plus sensor queries and a few others. Nothing in that file loads by itself. You copy what you want into printer.cfg.

What Mainsail and Fluidd add

Both interfaces publish a read-only config file, mainsail.cfg or fluidd.cfg, that you load with one line such as [include mainsail.cfg]. Their READMEs give the install steps for mainsail-config and fluidd-config. The two files carry the same macros:

Macro	What it does
PAUSE	Runs Klipper’s PAUSE, then retracts 1 mm, lifts 2 mm and parks 5 mm inside the X and Y maximums
RESUME	Reheats the nozzle if the printer went idle, refuses to start on a cold nozzle or an empty runout sensor, then returns and continues
CANCEL_PRINT	Retracts 5 mm, turns off heaters and the part fan, then cancels
SET_PAUSE_NEXT_LAYER, SET_PAUSE_AT_LAYER	Pause automatically at the next layer or a chosen layer

The file also enables [virtual_sdcard], [pause_resume], [display_status] and [respond]. To change park positions or retract lengths, copy its _CLIENT_VARIABLE macro into printer.cfg below the include and edit the values there. PAUSE, RESUME and CANCEL_PRINT covers that setup.

Useful Klipper macros list

Most Klipper printers end up with some version of these. The command names are conventions, not requirements. A macro can have any name, as long as your slicer and other macros call that exact name.

Macro	What it automates	Common command
Start print	Heats, homes, meshes and purges, so the slicer’s start G-code is one line (PRINT_START macro)	PRINT_START or START_PRINT
End print	Retracts, lifts and parks the head, then turns off heaters, fan and motors (END_PRINT macro)	PRINT_END or END_PRINT
Pause, resume, cancel	Parks safely on pause, reheats on resume, shuts down on cancel (setup)	PAUSE, RESUME, CANCEL_PRINT
Filament change	Pauses, parks and unloads when the slicer inserts M600 at a layer (M600 macro)	M600
Runout response	Pauses when a filament sensor reports empty and runs your G-code (runout sensor)	runout_gcode in [filament_switch_sensor]
Purge line	Primes the nozzle with a line beside the print before the first layer (purge line)	your own, or LINE_PURGE from KAMP (Klipper Adaptive Meshing and Purging)
Nozzle wipe	Drags the nozzle across a brush to clear ooze before probing or printing (nozzle wipe)	CLEAN_NOZZLE
Adaptive mesh	Probes only the area this file’s objects cover (adaptive meshing)	BED_MESH_CALIBRATE ADAPTIVE=1
Z offset per plate	Applies the saved Z offset for the build plate in use (per-plate offset)	SET_GCODE_OFFSET with [save_variables]
Chamber heat soak	Heats the chamber and waits before homing, and adds M141 and M191 (chamber heater control)	M141, M191
Cancel one object	Skips a failed part and keeps printing the rest (exclude object)	EXCLUDE_OBJECT, M486
Startup tasks	Runs G-code once Klipper is ready, after a delay, or on repeat (startup macros)	[delayed_gcode]
On-screen prompts	Shows a dialog with buttons in Mainsail or Fluidd and runs G-code from the choice (user input)	RESPOND TYPE=command MSG="action:prompt_begin ..."

Two rows depend on other config. Adaptive meshing reads the object outlines a sliced file defines, so it needs [exclude_object] and a file with object labels, which the slicer or an upload preprocessor adds. Prompts need the [respond] module and a current Mainsail or Fluidd (version details).

Klipper macro examples

Three short macros show the patterns most others are built from.

An alias that hands a slicer’s M600 to Mainsail’s PAUSE, as the comments in mainsail.cfg suggest, with a park position and a minimum height:

[gcode_macro M600]
description: Filament change
gcode:
    PAUSE X=10 Y=10 Z_MIN=50    ; park front left, at least 50 mm above the bed

A start macro that takes temperatures from the slicer and falls back to defaults, trimmed from Klipper’s sample:

[gcode_macro START_PRINT]
gcode:
    {% set BED_TEMP = params.BED_TEMP|default(60)|float %}
    {% set EXTRUDER_TEMP = params.EXTRUDER_TEMP|default(190)|float %}
    M140 S{BED_TEMP}            ; start heating the bed
    G90
    G28                         ; home while the bed heats
    M190 S{BED_TEMP}            ; wait for the bed
    M109 S{EXTRUDER_TEMP}       ; heat the nozzle and wait

The slicer then calls it with one line, for example START_PRINT BED_TEMP=60 EXTRUDER_TEMP=210. Klipper’s Slicers page notes the benefit: start and end changes “do not require re-slicing.”

A guard that refuses to run unless the printer is homed:

[gcode_macro CHECK_HOMED]
gcode:
    {% if "xyz" not in printer.toolhead.homed_axes %}
      { action_raise_error("Home the printer first (G28)") }
    {% endif %}

Call CHECK_HOMED at the top of any macro that moves the head. Klipper evaluates a called macro only when it is invoked, so the check sees the homed state at that moment. If it fails, action_raise_error stops the calling macro too.