{"id":4353,"library":"esp-idf-kconfig","title":"ESP-IDF Kconfig Tooling","description":"esp-idf-kconfig is a Python library that provides Kconfig tooling for the Espressif IoT Development Framework (ESP-IDF). It enables project configuration using the Kconfig language, offers IDE support for configuration, and facilitates documentation generation. As of version 3.7.0, it is actively developed and forms a core part of the ESP-IDF 6.x ecosystem. Its release cadence aligns with ESP-IDF updates.","status":"active","version":"3.7.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/esp-idf-kconfig","tags":["espressif","embedded","project","configuration","kconfig","esp-idf"],"install":[{"cmd":"pip install esp-idf-kconfig","lang":"bash","label":"Latest stable version"}],"dependencies":[{"reason":"Used for parsing Kconfig files. Specific versions are often required for compatibility.","package":"pyparsing","optional":false},{"reason":"Required for the terminal-based menuconfig interface to function correctly on Windows systems.","package":"windows-curses","optional":true}],"imports":[{"note":"The `esp-idf-kconfig` package integrates and extends `kconfiglib`. For programmatic interaction with Kconfig objects (e.g., parsing files, accessing symbols), import `Kconfig` directly from `kconfiglib`.","symbol":"Kconfig","correct":"from kconfiglib import Kconfig"},{"note":"Used for providing Kconfig configuration server functionality, typically for IDE integration.","symbol":"KconfServer","correct":"from esp_idf_kconfig.kconfserver import KconfServer"},{"note":"Used for advanced Kconfig file manipulation and generation tasks.","symbol":"KconfigGen","correct":"from esp_idf_kconfig.kconfgen import KconfigGen"}],"quickstart":{"code":"import os\nfrom kconfiglib import Kconfig\n\n# Create a dummy Kconfig file for demonstration\nwith open('Kconfig.example', 'w') as f:\n    f.write('config MY_OPTION\\n')\n    f.write('    bool \"My boolean option\"\\n')\n    f.write('    default y\\n')\n    f.write('\\n')\n    f.write('config MY_STRING_OPTION\\n')\n    f.write('    string \"My string option\"\\n')\n    f.write('    default \"hello\"\\n')\n\n# Load the Kconfig file\ntry:\n    # Path to the Kconfig file (can be Kconfig or Kconfig.projbuild)\n    kconf = Kconfig('Kconfig.example')\n\n    # Access a symbol\n    my_option = kconf.syms['MY_OPTION']\n    print(f\"MY_OPTION: {my_option.str_value}\")\n\n    my_string_option = kconf.syms['MY_STRING_OPTION']\n    print(f\"MY_STRING_OPTION: '{my_string_option.str_value}'\")\n\n    # Simulate loading an sdkconfig file (empty for defaults)\n    # In a real scenario, this would load a previously saved config\n    with open('sdkconfig.temp', 'w') as f:\n        f.write('# CONFIG_MY_OPTION is not set\\n')\n        f.write('CONFIG_MY_STRING_OPTION=\"world\"\\n')\n\n    kconf.load_config('sdkconfig.temp')\n\n    print(f\"MY_OPTION after loading sdkconfig: {kconf.syms['MY_OPTION'].str_value}\")\n    print(f\"MY_STRING_OPTION after loading sdkconfig: '{kconf.syms['MY_STRING_OPTION'].str_value}'\")\n\nfinally:\n    # Clean up dummy files\n    if os.path.exists('Kconfig.example'):\n        os.remove('Kconfig.example')\n    if os.path.exists('sdkconfig.temp'):\n        os.remove('sdkconfig.temp')","lang":"python","description":"This quickstart demonstrates how to programmatically interact with Kconfig files using the underlying `kconfiglib` module, which is integrated into `esp-idf-kconfig`. It shows how to load a Kconfig definition, access configuration symbols, and simulate loading a configuration from an `sdkconfig` file. Most users will interact with Kconfig via the `idf.py menuconfig` command-line tool within an ESP-IDF project environment."},"warnings":[{"fix":"Review the official migration guide from v2.x to v3.x and update Kconfig files to comply with the new syntax and rules, including replacing `---help---` with proper indented help blocks. Use `sdkconfig.rename` files for backward compatibility of renamed options.","message":"Migration from esp-idf-kconfig v2.x to v3.x involved significant breaking changes to the Kconfig language syntax. Removed `---help---` keyword, `def_<type>` options, and restricted `config` and `choice` names to uppercase, numbers, and underscores. Preprocessor macros are also limited.","severity":"breaking","affected_versions":"3.0.0 and above"},{"fix":"Ensure that the installed `pyparsing` version is compatible with your `esp-idf-kconfig` version, especially when updating ESP-IDF or `esp-idf-kconfig`. Check ESP-IDF's `requirements.txt` for recommended `pyparsing` version ranges.","message":"Specific versions of the `pyparsing` library are often required for compatibility, and mismatches can lead to parsing errors. For example, `esp-idf-kconfig v3.4.2` required updates to comply with `pyparsing 3.3.1`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `windows-curses` explicitly via `pip install windows-curses` in your Python environment if you are using `idf.py menuconfig` on Windows.","message":"On Windows, the terminal-based `menuconfig` interface may fail to launch or function correctly if the `windows-curses` package is not installed.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Update to the latest `esp-idf-kconfig` version to benefit from bug fixes related to Kconfig parsing and default value handling. Ensure Kconfig dependencies are correctly defined.","message":"Unexpected behavior with default values and invisible choices has been observed and fixed in various releases. This can manifest as crashes or incorrect configuration reports when certain options are not visible or dependencies are not correctly respected.","severity":"gotcha","affected_versions":"<3.7.0"},{"fix":"Regularly update your project's `sdkconfig` to use the latest Kconfig option names. Consult `sdkconfig.rename` files to understand mappings but strive to eliminate reliance on deprecated options in your Kconfig definitions.","message":"Older Kconfig option names that change across ESP-IDF versions are managed through `sdkconfig.rename` files. While these files provide backward compatibility, relying heavily on deprecated options can lead to maintainability issues and make upgrades more complex.","severity":"deprecated","affected_versions":"All versions (related to ESP-IDF project configuration)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}