# Project Configuration

In smaller projects (e.g. command line utility like `grep` command), it is often enough to configure it e.g. via command line parameters. When the projects gets larger, dedicated configuration files (C/C++ header files, YAML, JSON etc.) are often used with parameters altering the code behavior. However, as the number of configuration options grows, it becomes more and more difficult to manage them. Furthermore, different parts of the project (think of e.g. IDE plugins) can have different ways of configuring.

ESP-IDF project unified the way to configure the project, build system, ESP-IDF framework itself and external components. This configuration tool is called Kconfig.

Kconfig tool uses distributed structure of configuration files of the same name (`Kconfig`). These files contain the definition of configuration options (e.g. name, type) and may contain their default values. Every component has its own `Kconfig` file. Their discovery is done automatically by the configuration tool.

Values currently assigned to the configuration options are then stored in one sdkconfig file in the project's root folder. This file is specific for the given project and is changed every time user makes a change in any of the configuration option's value. For the purpose of editing the configuration, the menuconfig tool is used. The values of the configuration options are also propagated to the CMake scripts and C code via `sdkconfig.h` and `sdkconfig.cmake` files.

For the purpose of setting user-defined default values for configuration options, the sdkconfig.defaults file can be used. This approach is also preferred in the situation when the project is under version control. This file is used to replace default values set by `Kconfig` files when the project is configured the first time and no `sdkconfig` is present, but those values can still be changed by the user via configuration tools (e.g. `idf.py menuconfig`).

- ESP-IDF Project Configuration Guide
  - Editing the Configuration
  - How to Use Configuration Variables in C Code and CMake
  - Defining New Configuration Options for the Project
- Configuration Files and Structure
  - Kconfig and Kconfig.projbuild Files
  - sdkconfig.rename and sdkconfig.rename.<chip>
- Defining configuration options of components
  - How Configuration Works in ESP-IDF
  - How to Define New Configuration Options for Your Component
  - How to Ensure Backward Compatibility

Note

For the detailed information about Kconfig language or `esp-idf-kconfig`, which is the package of tools for the ESP-IDF configuration, please refer to the to the lower-level and more implementation-focused esp-idf-kconfig documentation.

Note

For the complete list of configuration options, please refer to the Configuration Options Reference and in the top left corner, choose your combination of a chip and ESP-IDF version.

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.