Install & Compatibility
Where this runs
tested against v14.1.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.010s · 18.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.008s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Kconfig
✓ from kconfiglib import Kconfig
Symbol
✓ from kconfiglib import Symbol
Kconfiglib 1.x API
✓
✗ kconfig.sym_value("FOO")
Kconfiglib 2.x (current) replaced functions with properties for accessing symbol values and other object attributes. The Kconfiglib 1.x API is not backwards-compatible.
This quickstart demonstrates how to load a Kconfig file, access symbols, query their properties, and programmatically set their values. It showcases how symbol values are affected by their dependencies.
import os
from kconfiglib import Kconfig
# Create a dummy Kconfig file for demonstration
kconfig_content = """
menu "My Application Configuration"
config MY_FEATURE_ENABLED
bool "Enable My Feature"
default y
config MY_STRING_SETTING
string "My String Setting"
default "default_value"
depends on MY_FEATURE_ENABLED
endmenu
"""
with open("Kconfig_example", "w") as f:
f.write(kconfig_content)
# Load the Kconfig file
kconf = Kconfig("Kconfig_example")
# Access a symbol by its name
feature_symbol = kconf.syms["MY_FEATURE_ENABLED"]
string_symbol = kconf.syms["MY_STRING_SETTING"]
# Print symbol information
print(f"Symbol: {feature_symbol.name}, Prompt: '{feature_symbol.prompt}', Value: {feature_symbol.str_value}")
print(f"Symbol: {string_symbol.name}, Prompt: '{string_symbol.prompt}', Value: {string_symbol.str_value}")
# Set a symbol value
feature_symbol.set_value(0) # Set to 'n'
print(f"Updated {feature_symbol.name} value: {feature_symbol.str_value}")
# Try to set string_symbol, which now depends on MY_FEATURE_ENABLED being 'y'
# This will fail silently or yield an 'n' if the dependency is not met
string_symbol.set_value("new_value")
print(f"Updated {string_symbol.name} value: {string_symbol.str_value} (expected empty if feature disabled)")
# Re-enable MY_FEATURE_ENABLED and set string_symbol
feature_symbol.set_value(2) # Set to 'y'
string_symbol.set_value("new_value_2")
print(f"Updated {string_symbol.name} value: {string_symbol.str_value} (expected 'new_value_2')")
# Clean up the dummy Kconfig file
os.remove("Kconfig_example")
Debug
Known issues
breakingKconfiglib 2.x is not backwards-compatible with Kconfiglib 1.x. The API changed significantly, replacing functions with properties for accessing symbol values and menu structures. Code written for Kconfiglib 1.x will break.fixRefer to the Kconfiglib 2.x documentation and `kconfiglib-2-changes.txt` for migration details. Update code to use properties (e.g., `symbol.str_value` instead of `symbol.get_value()`).
affects: < 2.0.0
breakingStarting with Kconfiglib 13.0.0, the `windows-curses` package is no longer automatically installed on Windows. This dependency is required for the terminal `menuconfig` interface to function.fixManually install `windows-curses` on Windows if you intend to use the terminal `menuconfig`: `pip install windows-curses`.
affects: >= 13.0.0
deprecatedThe old syntax for referencing environment variables as `$FOO` is deprecated. The new syntax is `$(FOO)`. While the old syntax is currently supported for compatibility with older Linux kernels, it might be removed in a future major version.fixUpdate Kconfig files to use `$(FOO)` for environment variable references.
affects: All versions
gotchaAssignments to hidden (promptless) symbols in configuration files are ignored. These symbols derive their values indirectly from other symbols via `default` or `select`. It's a common mistake to assume such assignments in a `.config` file will be respected when read back by Kconfiglib.fixAvoid direct assignments to hidden symbols in `.config` files. Configure their controlling symbols instead.
affects: All versions
gotchaOverusing `select` statements in Kconfig can lead to complex and hard-to-debug dependency issues. Changes to a selected symbol's dependencies often require propagating those changes to all symbols that select it, which is easily overlooked.fixConsider using `depends on` instead of `select` where appropriate to make dependencies explicit and local. Avoid long chains of `select` statements.
affects: All versions
gotchaKconfiglib may fail to correctly parse `Kconfig.include` files from Linux kernel versions 5.12.1 and newer, leading to `ValueError: invalid literal for int() with base 10: 'error-if'` during parsing.fixThis is an active issue (as of the last check). Check Kconfiglib's GitHub issues for potential patches or workarounds. Ensure your Kconfiglib version is up-to-date, as this might be resolved in newer releases.
affects: All versions (when parsing kernel >= 5.12.1 Kconfig)
gotchaWithin Kconfig files, all hexadecimal literals must be prefixed with `0x` or `0X` to be correctly distinguished from symbol references by the parser.fixEnsure all hex values in Kconfig files adhere to the `0x...` or `0X...` format.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'kconfiglib'
The 'kconfiglib' package is not installed in your Python environment or the Python interpreter cannot locate it.
fixInstall the library using pip: `pip install kconfiglib`
kconfiglib.KconfigError: <filename>:<line>: error: couldn't parse 'transitional': syntax error
Your version of kconfiglib is outdated and does not support newer Kconfig language features or syntax, such as the 'transitional' attribute, introduced in recent Linux kernel versions.
fixUpgrade kconfiglib to the latest version: `pip install --upgrade kconfiglib`
AttributeError: 'MenuNode' object has no attribute 'help'
This error occurs when attempting to directly access a 'help' attribute on a `MenuNode` object. Help texts for symbols and choices are stored within their respective `MenuNode` objects but are accessed through the `Symbol` or `Choice` objects associated with those nodes, or via specific `kconfiglib` methods.
fixRefer to the kconfiglib documentation for the correct way to access help text for symbols or menu nodes, typically through properties of the `Symbol` object linked to the `MenuNode` (e.g., `symbol.help`).
error: externally-managed-environment
On Python 3.11 and later, system-wide Python environments are marked as 'externally managed' (PEP 668) to prevent accidental modification by pip outside of a virtual environment.
fixCreate and activate a Python virtual environment (`python -m venv .venv && source .venv/bin/activate`) before installing kconfiglib, or use `pip install kconfiglib --break-system-packages` (use with caution).
kconfiglib.KconfigError: Config file not found: <path_to_config_file>
The Kconfig file specified, or implicitly expected by kconfiglib, does not exist at the given path, or the `base_dir` parameter for resolving 'source' statements is incorrect.
fixEnsure the path to your Kconfig file is correct. If using `kconfiglib.Kconfig()`, explicitly provide the correct `filename` and `base_dir` arguments, ensuring `base_dir` points to the root of your Kconfig tree.
Upgrade
Version history
14.1.0latest on PyPI · released Jan 31, 2020
Audit
Dependencies
pythonrequiredThe library is written in Python.
windows-cursesoptionalRequired for the terminal menuconfig interface on Windows.