Klipper’s printer.cfg - Syntax and Parsing Rules

Knowledge Base
1

Klipper’s printer.cfg - Syntax and Parsing Rules

Table of Contents

  1. Overview
  2. File Structure and Syntax
  3. Includes and the SAVE_CONFIG Block
  4. Parsing Logic: How Klipper Builds the Configuration
  5. Practical Examples
  6. Conclusion

Overview

Klipper relies on a structured configuration file - the printer.cfg - to define how the firmware interacts with the printer’s hardware. At every startup, Klipper parses this file (along with any included files) to generate the effective configuration. Understanding how this process works is crucial for troubleshooting unexpected behavior, avoiding configuration conflicts, and maintaining a clean setup.

:light_bulb: Important: The parsed result is recorded in the klippy.log file, which acts as the single source of truth for determining what configuration is actually in use. If ever something is not working as expected, reviewing the parsed output in klippy.log is the first step.

File Structure and Syntax

Sections and Settings

  • The configuration is divided into sections, each marked by a header like [stepper_x] or [extruder].

  • Each section contains settings, usually in the form option: value (or optionally option = value). For example:

    kinematics: corexy
step_pin: PA1

Multiline Values

Some settings support multiline values, such as:

  • gcode:
  • alias:
  • gantry_corners:

For these, each line of the value must be indented by at least one space or tab. For better readability, 4 spaces or a tab are recommended.

Example: 
gantry_corners:
    -60,-10
    360,370

Syntax Rules

  • Section headers and setting names must not be indented. Incorrect indentation, especially for sections or settings, is a frequent cause of Klipper failing to start, often reported as some sort of configuration error.

  • Comments start with # or ;. For inline comments (appearing after a section or setting), the # or ; must be preceded by at least one space.

    step_pin: PA1  # Stepper driver pin

  • Comments do not appear in the parsed config within klippy.log, though full-line comments result in a blank line.

Case Sensitivity

Klipper is case-sensitive in most cases:

  • Case-sensitive: Section names, setting names, pin names, bus names (I2C/SPI)
  • Case-insensitive: G-code command and parameter names

Includes and the SAVE_CONFIG Block

Included Configuration Files

You can modularize your setup using includes:

[include mainsail.cfg]
[include macros/*.cfg]

These external files follow the same rules as printer.cfg and are merged into the configuration at the point they are included.

The SAVE_CONFIG Section

At the bottom of the printer.cfg, you may find an auto-generated block like this:

#*# <---------------------- SAVE_CONFIG ----------------------->
#*# DO NOT EDIT THIS BLOCK OR BELOW. The contents are auto-generated.

This section is automatically created when you use tuning commands (e.g., PID_CALIBRATE, Z_OFFSET_APPLY, etc.) and commit the tuning results with the SAVE_CONFIG command. Once values are stored here, their original definitions elsewhere in the config are commented out.

:warning: Important Notes:

  • SAVE_CONFIG only works correctly if the original values are in the main printer.cfg, not in included files. Otherwise, Klipper will throw a conflict error during saving. See this article for more details.
  • If the SAVE_CONFIG section contains values that are no longer valid, such as an auto-saved Z-offset for a removed BLTouch sensor, manual intervention is required. In such cases, it is safe to carefully remove or update those entries, making sure to keep the overall formatting intact.

Parsing Logic: How Klipper Builds the Configuration

Klipper builds the configuration by parsing files from top to bottom:

  1. The main printer.cfg is read in order.
  2. As [include] directives are encountered, those files are immediately read and parsed in place.
  3. If a section appears more than once:
    • Its settings are merged under the respective section when unique.
    • If a setting appears twice in the same section (potentially in a different location or from an included file), the last occurrence wins, thus overwriting the earlier one.
  4. If a setting appears in both the regular config and the SAVE_CONFIG-block, the regular config takes precedence.

Practical Examples

Here are a few examples to illustrate the rules above. In any case, it does not matter if the source for certain sections or settings is within the printer.cfg file or comes from an included file.

Overwriting a Setting

[heater_bed]
control: pid

...

[heater_bed]
control: watermark

:right_arrow: Result: control: watermark will be used, as it appears later.

Merging Sections

[printer]
kinematics: corexy

...

[printer]
max_velocity: 300

:right_arrow: Result: Both kinematics and max_velocity will be present.

SAVE_CONFIG Precedence

[heater_bed]
pid_Kp: 50.0  # This is in the main config

#*# <---------------------- SAVE_CONFIG ----------------------->
#*# DO NOT EDIT THIS BLOCK OR BELOW. The contents are auto-generated.
#*#
#*# [heater_bed]
#*# pid_Kp: 47.2

:right_arrow: Result: The value 50.0 from the main config is used.

Conclusion

Understanding Klipper’s configuration parsing model is key to building a robust and predictable setup. By knowing how and when values are read, merged, or overwritten - and by inspecting the klippy.log- issues can be avoided or more easily debugged.

The level of modularity with includes is a matter of personal preference. Care must be taken, as this modularity often comes at the cost of transparency. Adhering to the above rules becomes crucial.

5 Likes