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:

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.

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.