# Klipper’s printer.cfg - Syntax and Parsing Rules **URL:** \ **Category:** Knowledge Base\ **Created:** [May 13, 2025, 6:09pm UTC](https://klipper.discourse.group/t/klipper-s-printer-cfg-syntax-and-parsing-rules/23425 "2025-05-13T18:09:09Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Sineos](https://yyz2.discourse-cdn.com/free1/user_avatar/klipper.discourse.group/sineos/32/18_2.png) [@Sineos](https://klipper.discourse.group/u/Sineos)\ **Post date:** [May 13, 2025, 6:09pm UTC](https://klipper.discourse.group/t/klipper-s-printer-cfg-syntax-and-parsing-rules/23425/1 "2025-05-13T18:09:09Z")
# Klipper’s printer.cfg - Syntax and Parsing Rules ## Table of Contents 1. [Overview](#p-76395-overview-3) 2. [File Structure and Syntax](#p-76395-file-structure-and-syntax-4) - [Sections and Settings](#p-76395-sections-and-settings-5) - [Multiline Values](#p-76395-multiline-values-6) - [Syntax Rules](#p-76395-syntax-rules-7) - [Case Sensitivity](#p-76395-case-sensitivity-8) 3. [Includes and the SAVE\_CONFIG Block](#p-76395-includes-and-the-save_config-block-9) - [Included Configuration Files](#p-76395-included-configuration-files-10) - [The SAVE\_CONFIG Section](#p-76395-the-save_config-section-11) 4. [Parsing Logic: How Klipper Builds the Configuration](#p-76395-parsing-logic-how-klipper-builds-the-configuration-12) 5. [Practical Examples](#p-76395-practical-examples-13) 6. [Conclusion](#p-76395-conclusion-17) ## 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. > 💡 **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: ### 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:** > > ```kcfg > 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. - 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: ```kcfg [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: ```auto #*# <---------------------- 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. > ⚠ **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](https://klipper.discourse.group/t/save-config-section-bltouch-option-z-offset-conflicts-with-included-value/6640) 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 ```kcfg [heater_bed] control: pid ... [heater_bed] control: watermark ``` ➡ Result: `control: watermark` will be used, as it appears later. ### Merging Sections ```kcfg [printer] kinematics: corexy ... [printer] max_velocity: 300 ``` ➡ Result: Both `kinematics` and `max_velocity` will be present. ### SAVE\_CONFIG Precedence ```kcfg [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 ``` ➡ 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.