Install & Compatibility
Where this runs
tested against v3.12.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.138s · 41.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.138s · 42MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Kconfig
✓ from kconfiglib import Kconfig
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`.
KconfServer
✓ from esp_idf_kconfig.kconfserver import KconfServer
Used for providing Kconfig configuration server functionality, typically for IDE integration.
KconfigGen
✓ from esp_idf_kconfig.kconfgen import KconfigGen
Used for advanced Kconfig file manipulation and generation tasks.
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.
import os
from kconfiglib import Kconfig
# Create a dummy Kconfig file for demonstration
with open('Kconfig.example', 'w') as f:
f.write('config MY_OPTION\n')
f.write(' bool "My boolean option"\n')
f.write(' default y\n')
f.write('\n')
f.write('config MY_STRING_OPTION\n')
f.write(' string "My string option"\n')
f.write(' default "hello"\n')
# Load the Kconfig file
try:
# Path to the Kconfig file (can be Kconfig or Kconfig.projbuild)
kconf = Kconfig('Kconfig.example')
# Access a symbol
my_option = kconf.syms['MY_OPTION']
print(f"MY_OPTION: {my_option.str_value}")
my_string_option = kconf.syms['MY_STRING_OPTION']
print(f"MY_STRING_OPTION: '{my_string_option.str_value}'")
# Simulate loading an sdkconfig file (empty for defaults)
# In a real scenario, this would load a previously saved config
with open('sdkconfig.temp', 'w') as f:
f.write('# CONFIG_MY_OPTION is not set\n')
f.write('CONFIG_MY_STRING_OPTION="world"\n')
kconf.load_config('sdkconfig.temp')
print(f"MY_OPTION after loading sdkconfig: {kconf.syms['MY_OPTION'].str_value}")
print(f"MY_STRING_OPTION after loading sdkconfig: '{kconf.syms['MY_STRING_OPTION'].str_value}'")
finally:
# Clean up dummy files
if os.path.exists('Kconfig.example'):
os.remove('Kconfig.example')
if os.path.exists('sdkconfig.temp'):
os.remove('sdkconfig.temp')
Debug
Known issues
breakingMigration 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.fixReview 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.
affects: 3.0.0 and above
gotchaSpecific 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`.fixEnsure 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.
affects: All versions
gotchaOn Windows, the terminal-based `menuconfig` interface may fail to launch or function correctly if the `windows-curses` package is not installed.fixInstall `windows-curses` explicitly via `pip install windows-curses` in your Python environment if you are using `idf.py menuconfig` on Windows.
affects: All versions on Windows
gotchaUnexpected 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.fixUpdate 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.
affects: <3.7.0
deprecatedOlder 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.fixRegularly 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.
affects: All versions (related to ESP-IDF project configuration)
Errors
Common errors & fixes
AttributeError: module 'kconfiglib' has no attribute 'ConfigType'
This error typically occurs due to a version mismatch between the installed `kconfiglib` Python package and the version expected by your ESP-IDF installation, often after an ESP-IDF update.
fixEnsure your ESP-IDF Python environment dependencies are correctly installed and updated for your specific IDF version. Run `python -m pip install -U kconfiglib` or re-run `idf.py install-python-dependencies` within your ESP-IDF environment. You might need to explicitly set the correct `kconfiglib` version as specified by your ESP-IDF's `requirements.txt`.
kconfiglib.KconfigError: ... not found (in 'source "$COMPONENT_KCONFIGS_PROJBUILD"')
This KconfigError indicates that a Kconfig file or a path referenced within a Kconfig 'source' statement cannot be found by the Kconfig parsing tools. This can be due to incorrect paths, missing files, or issues with environment variables like `$COMPONENT_KCONFIGS_PROJBUILD` not expanding correctly.
fixVerify that all Kconfig files (e.g., `Kconfig`, `Kconfig.projbuild`) exist at their expected locations and that any environment variables used in `source` statements are correctly defined and resolve to valid paths. Check for typos in file names or paths within your Kconfig files. For issues like `build/Kconfig` not being generated, ensure your ESP-IDF version and build system are correctly set up and consider workarounds like manually creating an empty `build/Kconfig` if it's a known regression.
ModuleNotFoundError: No module named 'kconfiglib'
The `kconfiglib` Python package, which `esp-idf-kconfig` depends on, is not installed or is not accessible within the Python environment being used by ESP-IDF.
fixActivate your ESP-IDF Python virtual environment and install `kconfiglib` using pip: `pip install kconfiglib`. If using the ESP-IDF tools, you can run `idf.py install-python-dependencies` to ensure all required packages are installed.
idf.py menuconfig failed with error: curses.error: nocbreak() returned ERR
This error often occurs when the terminal environment used to run `idf.py menuconfig` does not properly support the `curses` library, which is used to render the text-based user interface. This is common in minimalist terminals, SSH sessions without proper `TERM` settings, or on Windows with certain console emulators.
fixEnsure you are using a compatible terminal (e.g., WSL terminal on Windows, a full-featured terminal emulator on Linux/macOS). Check your `TERM` environment variable (e.g., `export TERM=xterm-256color`). If connecting via SSH, ensure `ssh -X` or `ssh -Y` is used for X11 forwarding if curses falls back to graphical mode, or that your remote `TERM` is correctly set.
kconfiglib.KconfigError: ... error: couldn't parse 'set default ...': syntax error
This specific syntax error, often with `set default`, indicates that the Kconfig file uses syntax that is not supported by the version of `kconfiglib` or ESP-IDF's Kconfig tools being used. This can happen if you are using a newer Kconfig feature with an older ESP-IDF version.
fixConsult the ESP-IDF documentation for your specific version to understand the supported Kconfig syntax. If `set default` is not supported, you may need to define default values using the `default` keyword within a `config` entry or upgrade your ESP-IDF to a version that supports the desired syntax. If migrating from an older `esp-idf-kconfig` version, review the migration guide for syntax changes.
Upgrade
Version history
3.12.0latest on PyPI · released Jul 20, 2026
Audit
Dependencies
pyparsingrequiredUsed for parsing Kconfig files. Specific versions are often required for compatibility.
windows-cursesoptionalRequired for the terminal-based menuconfig interface to function correctly on Windows systems.