A Klipper macro is a config section, so adding one means editing a file in the config folder and restarting. This page covers where the file goes, how to include it, the errors you hit when the path is wrong, and why a macro can load without appearing as a button.
To add a macro to Klipper, write a [gcode_macro NAME] section with an indented gcode: block in printer.cfg, or in a file such as macros.cfg that printer.cfg loads with [include macros.cfg]. Then send RESTART, or click Save & Restart in the editor. The macro is now a command you can type in the console or click in the Macros panel.
How to add a macro in Klipper
- Open the config folder. In Mainsail it is the config file list on the Machine page. In Fluidd it is the
config root of the file manager. Over SSH it is ~/printer_data/config/.
- Create a macro file. Add a new file named
macros.cfg next to printer.cfg. Klipper does not create one for you.
- Write the macro. Paste a
[gcode_macro] section like the one below and save.
- Include the file. Add
[include macros.cfg] to printer.cfg, above the #*# <---------------------- SAVE_CONFIG ----------------------> block if the file has one.
- Restart Klipper. Click Save & Restart, or send
RESTART in the console. Klipper reads its config only when it starts.
- Run it. Type the macro name in the console.
HELP lists it with its description.
[gcode_macro PARK_FRONT]
description: Lift the nozzle 10 mm and park at the front of the bed
gcode:
{% if printer.toolhead.homed_axes != "xyz" %}
G28
{% endif %}
SAVE_GCODE_STATE NAME=park_front
G91
G1 Z10 F600 ; lift 10 mm from where the nozzle is
G90
G1 X110 Y10 F6000 ; placeholder: front center of your bed
RESTORE_GCODE_STATE NAME=park_front
The macro homes only when printer.toolhead.homed_axes shows an unhomed axis, and the SAVE_GCODE_STATE / RESTORE_GCODE_STATE pair leaves absolute or relative mode as it found it. Change X and Y to suit your bed. If a 10 mm lift would pass the Z limit, Klipper stops with a move error.
Where do Klipper macros go?
Klipper macros go in any .cfg file that Klipper reads at startup: printer.cfg itself, or a file it includes. On a current install those files sit in ~/printer_data/config/, the folder Mainsail and Fluidd show as the config root. A macro in a file that nothing includes is never loaded.
The folder comes from Moonraker’s default data path, $HOME/printer_data. Older installs used ~/klipper_config, and Moonraker’s documentation shows upgraded systems linking printer_data/config to it.
Klipper resolves an include path from the folder of the file holding the [include] line, not from your home folder. Wildcards work, which suits a folder of small files:
[include macros.cfg] ; ~/printer_data/config/macros.cfg
[include macros/*.cfg] ; every .cfg in ~/printer_data/config/macros/
Klipper loads wildcard matches in sorted order. When two files define the same section, Klipper merges them and the value read last wins. A comment in Klipper’s config loader says overrides “apply linearly as they do within a single file.”
Mainsail and Fluidd each have a client file, mainsail.cfg or fluidd.cfg, loaded the same way with [include mainsail.cfg] or [include fluidd.cfg]. Both define PAUSE, RESUME and CANCEL_PRINT. Mainsail’s documentation is blunt: “Do not edit mainsail.cfg directly.” Both files are customized instead by copying their _CLIENT_VARIABLE macro into printer.cfg and changing its values.
How to write a Klipper macro
A macro needs a name and a gcode: option. Everything else is optional. Two formatting rules apply, both from Klipper’s command templates page:
- Indentation. “The
gcode: config option always starts at the beginning of the line and subsequent lines in the G-Code macro never start at the beginning.”
- Names. Case does not matter, so
park_front and PARK_FRONT are the same command. Digits must come at the end: “TEST_MACRO25 is valid, but MACRO25_TEST3 is not.” Klipper refuses an invalid name at startup with Can't register '...' as it is an invalid name.
The gcode: block is a Jinja2 template. { } inserts a value and {% %} holds logic such as if and set. Klipper says macros “are first evaluated in entirety and only then are the resulting commands executed”, so a value read inside the macro does not change partway through it. For arguments, see macro parameters. For values that persist between calls, see macro variables.
For starting points, Klipper’s repository has a sample-macros.cfg of snippets to copy into your config and adjust.
How to install a downloaded Klipper macro file
A macro pack is one or more .cfg files and installs like your own file. Copy it, or git clone its repository, into ~/printer_data/config/. Add an [include] line pointing at it, then restart. Read the pack’s instructions first, since a pack can need config sections of its own. If it defines a macro you already have, the two sections merge option by option, and the result may match neither.
How to edit Klipper macros
Open the file in the web interface’s editor, change it and click Save & Restart. Saving alone changes nothing, because Klipper keeps running the config it loaded. Mainsail’s Save & Restart sends FIRMWARE_RESTART by default; the editor settings can switch it to RESTART. For a macro edit, RESTART is enough, since Klipper’s G-code reference says it causes “the host software to reload its config.” Fluidd’s editor saves and restarts on Ctrl+Alt+S (Cmd+Alt+S on a Mac). Over SSH, edit with nano ~/printer_data/config/macros.cfg, then send RESTART.
“macros.cfg does not exist” error
Klipper stops at startup with this error when an [include] names a single file that is not there:
Include file '/home/pi/printer_data/config/macros.cfg' does not exist
The path in the message is where Klipper looked. Check three things:
- The file was never created. Klipper does not create a
macros.cfg. Create it, or delete the include line.
- It is in another folder. The path is relative to the file holding the include. A
macros.cfg in your home folder is not found from printer_data/config/printer.cfg.
- The name differs. Linux file names are case sensitive, so
Macros.cfg and macros.cfg are different files.
A wildcard include behaves differently. Klipper’s loader accepts an empty match, so [include macros/*.cfg] with nothing in the folder loads no macros and reports no error.
Why are my Klipper macros not showing?
Klipper macros usually fail to show for one of three reasons: Klipper never loaded the file (a config error or a missing include), the name starts with an underscore, or the web interface hides the macro in its settings. Check the console for errors first, then run HELP to see whether Klipper registered the command.
If HELP lists the macro, the interface is hiding it. If not, Klipper never loaded it. Work through the list:
- Config error. A config error stops Klipper at startup, so no macro loads. A macro named after an existing command without
rename_existing fails with gcode command ... already registered. See rename_existing.
- Not included. The file exists, but no
[include] points at it, or a wildcard matches nothing.
- No restart. The file was saved but Klipper was not restarted.
- Underscore prefix. Mainsail and Fluidd hide any macro whose name starts with
_.
- rename_existing. Mainsail also hides macros that use
rename_existing, such as PAUSE, because the built-in buttons already cover them.
- Mainsail settings. In Simple mode each macro has a visibility toggle. In Expert mode a macro shows only if it belongs to a group, and a group or macro can be set to show only while idle, paused or printing.
- Stale page. Fluidd’s troubleshooting advice is to refresh the browser after restarting Klipper.
How to hide a macro in Klipper
Start its name with an underscore, as in [gcode_macro _PARK_HELPER]. Mainsail and Fluidd both leave such macros out of the macro panel, and Mainsail’s macro settings list skips them too. The command still runs from the console and from other macros, so the prefix suits helper macros that only other macros call. To hide a macro in Mainsail without renaming it, switch off its toggle under Interface Settings, then Macros.
Klipper macro buttons in Mainsail and Fluidd
Every visible macro becomes a button with no extra config. By default, Mainsail lists them alphabetically in one Macros panel. Its Expert mode builds groups instead: each group is its own dashboard panel, with button colors and per-state visibility. Fluidd sorts macros into categories you create and gives each a color.
Mainsail reads a macro’s params.NAME references and their |default() values from the gcode: block. A macro that takes parameters gets an input form on its button, with each default shown as a placeholder.
Fluidd also adds a macro to the Toolhead card’s Tools menu when its name matches one Fluidd looks for:
| Action |
Macro names Fluidd detects |
| Load filament |
LOAD_FILAMENT, FILAMENT_LOAD, M701 |
| Unload filament |
UNLOAD_FILAMENT, FILAMENT_UNLOAD, M702 |
| Clean nozzle |
CLEAN_NOZZLE, NOZZLE_CLEAN, WIPE_NOZZLE, NOZZLE_WIPE, G12 |
| Park toolhead |
PARK_TOOLHEAD, TOOLHEAD_PARK, G27 |
How to add a description to a Klipper macro
Add a description: line to the section. Klipper shows it in the HELP output and in console autocomplete. Without one, the description defaults to “G-Code macro”.
[gcode_macro PARK_FRONT]
description: Lift the nozzle 10 mm and park at the front of the bed
gcode:
...
Mainsail shows the description as a tooltip on the macro button, unless it is still the default.
.jpg){kind=link}