{"id":4048,"library":"idf-component-manager","title":"Espressif IDF Component Manager","description":"The IDF Component Manager is a Python-based tool by Espressif that integrates with the ESP-IDF build system to download and manage components from the ESP Component Registry or Git repositories. It ensures that correct versions of all project dependencies are present during a CMake run. This library, currently at version 3.0.1, receives updates frequently, often tied to major ESP-IDF releases, with major version bumps indicating significant breaking changes.","status":"active","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/espressif/idf-component-manager.git","tags":["ESP-IDF","IoT","embedded","dependency manager","component","espressif"],"install":[{"cmd":"pip install idf-component-manager","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core functionality is tightly integrated with the ESP-IDF build system and requires a compatible version.","package":"esp-idf","optional":false},{"reason":"Requires Python 3.10 or newer (for v3.x+).","package":"python","optional":false}],"imports":[{"note":"The library is primarily used as a command-line tool via the 'idf.py' wrapper or direct module execution, rather than as a Python library imported into user scripts for its core component management functionality.","symbol":"idf_component_manager","correct":"python -m idf_component_manager <command>"},{"note":"The 'compote' CLI provides advanced workflows for the Component Manager, including publishing components.","symbol":"compote","correct":"compote <command>"}],"quickstart":{"code":"# Navigate to your ESP-IDF project directory\n# Add a dependency to your main component (e.g., 'example/cmp')\nidf.py add-dependency example/cmp\n\n# Or create a manifest file and then build\n# idf.py create-manifest\n# Edit main/idf_component.yml to add dependencies like:\n# dependencies:\n#   espressif/json: '^1.0.0'\n# Then, reconfigure and build your project:\n# idf.py reconfigure\n# idf.py build","lang":"bash","description":"The IDF Component Manager primarily operates through the `idf.py` command-line tool. This example demonstrates how to add a component dependency to your project, which automatically creates or updates the `idf_component.yml` manifest file and manages dependencies during the build process."},"warnings":[{"fix":"Upgrade Python to version 3.10 or later, or pin `idf-component-manager` to a version <3.0.0.","message":"Version 3.0.0 dropped support for Python versions older than 3.10. Projects using `idf-component-manager` 3.x.x must use Python 3.10 or newer.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your ESP-IDF installation to v6.0.0 or newer, or pin `idf-component-manager` to a version <3.0.0.","message":"Version 3.0.0 introduced breaking changes in ESP-IDF integration, requiring ESP-IDF version 6.0.0 or later. Older ESP-IDF versions are no longer supported by `idf-component-manager` v3.x.x.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove these environment variables from your build environment or scripts.","message":"Environment variables `IDF_COMPONENT_KNOWN_TARGETS` and `IDF_COMPONENT_MANAGER_KNOWN_TARGETS` were removed in version 3.0.0.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Consider restructuring your project to use the standard ESP-IDF project structure or manually manage components in 'IDF as a Lib' projects.","message":"The component manager is not fully supported in 'IDF as a Lib' projects (projects that use `IDF`'s `tools/cmake/idf_as_lib.cmake`). As of March 2024, it's primarily designed for projects using `IDF`'s `tools/cmake/project.cmake`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always run `idf.py reconfigure` after making manual changes to `idf_component.yml`.","message":"If you manually add or modify an `idf_component.yml` manifest file, you need to run `idf.py reconfigure` to ensure CMake picks up the changes and the component manager processes the new dependencies.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}