Add rename_existing to a macro named after a built-in command, and Klipper hands the original to a new name your macro can call. Here is how it works, a G28 example, when to use homing_override instead, and what each error means.
To override a built-in Klipper command, name a [gcode_macro] after it and add rename_existing: <NEW_NAME>. Klipper moves the original command to the new name, and your macro calls that name whenever it needs the original behavior.
[gcode_macro M117]
rename_existing: M117.1
gcode:
M117.1 {rawparams} ; the original M117; add your own lines around it
What does rename_existing do in Klipper?
It moves an existing G-code command to a new name so a macro can take the original name. When Klipper connects, it re-registers the built-in under the name you give in rename_existing, then registers your macro under the original name. Slicer G-code and other macros now run your macro, which can call the renamed original.
Klipper’s configuration reference describes the option as one that “will cause the macro to override an existing G-Code command and provide the previous definition of the command via the name provided here.” It also warns: “Care should be taken when overriding commands as it can cause complex and unexpected results.” After a restart, HELP lists the moved command with the description “Renamed builtin of ‘M117’”.
How to override a built-in command with a macro
- Name the macro after the command. Use
[gcode_macro G28] to take over G28.
- Choose the new name. Add
rename_existing: with a name of the same type (see the naming rules).
- Call the original. Inside
gcode:, call the new name and pass the caller’s parameters through with {rawparams}.
- Restart and test. Run
RESTART, check HELP for the renamed command, then run the command once by hand.
This override homes as usual, then lifts the nozzle 10 mm once Z is homed:
[gcode_macro G28]
rename_existing: G28.1
gcode:
G28.1 {rawparams} ; the original homing command, same arguments
_PARK_AFTER_HOME
[gcode_macro _PARK_AFTER_HOME]
gcode:
{% if 'z' in printer.toolhead.homed_axes %}
SAVE_GCODE_STATE NAME=park_after_home
G90
G1 Z10 F600 ; 10 mm is a placeholder, set your own height
RESTORE_GCODE_STATE NAME=park_after_home
{% endif %}
The homed check sits in a second macro on purpose. Klipper’s command templates page warns that macros “are first evaluated in entirety and only then are the resulting commands executed.” Inside the G28 macro, homed_axes would be read before G28.1 ran. A called macro is evaluated when it runs, so _PARK_AFTER_HOME sees the fresh result. The saved G-code state restores the caller’s G90/G91 mode.
rawparams is the full, unparsed argument string, so G28 X Y becomes G28.1 X Y. To read single arguments instead, see macro parameters.
Naming rules for the new name
- Classic G-codes keep their form. A letter followed by a number, like
G28, needs another letter-plus-number name. Klipper’s sample macros file uses M117.1. G28_BASE fails.
- Extended commands get an extended name.
PAUSE becomes PAUSE_BASE, in capitals, digits and underscores. Klipper registers the value as typed and rejects a lowercase pause_base.
- The new name must be free. It cannot match any existing command.
Klipper homing override macro: [homing_override] or a G28 macro
To change how a printer homes, use Klipper’s [homing_override] section instead of renaming G28. Its script replaces every G28, and a G28 inside the script runs the real homing, so no rename is needed. It can also set an axis position before homing; a renamed G28 has no such option.
[homing_override]
axes: xyz
set_position_z: 0 ; assume Z is at 0 so it may move before homing
gcode:
G90
G1 Z5 F600 ; lift the nozzle off the bed
G28 X Y ; real homing for X and Y
G1 X150 Y150 F6000 ; placeholder: your Z endstop or probe position
G28 Z ; real homing for Z
The configuration reference says the script “must home all axes”, even when the caller asked to home only one. With axes: z, the override runs only when Z is being homed. A set_position_ value “disables homing checks for that axis”, so keep the lift short. For sensorless homing, Klipper’s TMC drivers page says a homing macro “can be called from a homing_override config section”.
Use [homing_override] to change the homing sequence, and a G28 macro to add a step before or after normal homing. Pick one: both replace G28.
Overriding PAUSE, RESUME and CANCEL_PRINT
Check your web interface’s config first. Mainsail’s mainsail.cfg already overrides PAUSE, RESUME and CANCEL_PRINT, renaming the originals to PAUSE_BASE, RESUME_BASE and CANCEL_PRINT_BASE. The file is read-only. To add your own step, copy its _CLIENT_VARIABLE macro into printer.cfg and set variable_user_pause_macro, variable_user_resume_macro or variable_user_cancel_macro. Each takes a single command, so point it at one macro of your own. Writing these from scratch is covered in pause and resume macros.
How to rename your own macro
To rename a macro you wrote, change its section header and update every caller: slicer start G-code, other macros, any delayed_gcode. Klipper upper-cases the name, so [gcode_macro park_head] becomes PARK_HEAD. Save rename_existing for commands Klipper or a module already provides.
rename_existing errors and fixes
| Error |
Cause |
Fix |
gcode command G28 already registered |
A built-in name used without rename_existing, or the new name is taken |
Add rename_existing, or pick an unused name |
Existing command 'PAUSE' not found in gcode_macro rename |
The command does not exist, such as PAUSE without [pause_resume] |
Add the module that provides it, or drop rename_existing |
G-Code macro rename of different types ('G28' vs 'G28_BASE') |
A classic G-code was renamed to an extended name |
Use a letter-plus-number name such as G28.1 |
Can't register 'pause_base' as it is an invalid name |
Lowercase or invalid characters in an extended name |
Write it in capitals: PAUSE_BASE |
Macro G28 called recursively |
The macro calls its own name |
Call the renamed command instead |
