IDF Component Manager

The IDF Component Manager helps you add and manage third-party ESP-IDF components (such as button drivers, display drivers, sensor drivers, or protocol stacks) from the ESP Component Registry or Git repositories. It is integrated into the ESP-IDF build system and removes the need to download, copy, and wire up components manually in CMake.

---

How It Works

During idf.py build or idf.py reconfigure, the build system:

1. Reads each component's idf_component.yml manifest.
2. Downloads dependencies into the managed_components/ directory at the project root.
3. Writes dependencies.lock to record the resolved versions for reproducible builds.

---

Manifest File: idf_component.yml

Create an idf_component.yml file in a component directory (including main) to declare dependencies:

dependencies:
  # From the ESP Component Registry
  espressif/button: "^2.5.0"

  # From a Git repository
  some_custom_lib:
    git: "https://github.com/user/custom-repo.git"
    path: "sub_directory/my_component"

  # Minimum ESP-IDF version
  idf: ">=5.0"

[!NOTE] The managed_components/ directory is managed automatically. Do not edit files in this directory. Manual changes are lost when you run idf.py clean or update dependencies.

---

Common Commands

The component manager is integrated into idf.py.

Add a Dependency

# Add a dependency to main
idf.py add-dependency "espressif/button^2.5.0"

# Add a dependency to a custom component
idf.py add-dependency --component=my_sensor "espressif/button^2.5.0"

Create a Manifest Template

idf.py create-manifest
idf.py create-manifest --component=my_sensor

Resolve and Update Dependencies

idf.py reconfigure
idf.py update-dependencies

---

Advanced Topics

[!NOTE] For private component dependencies, dependency conflict resolution, offline cache configuration, and publishing to the ESP Component Registry, see the ESP Component Management and Usage Guide.