Skip to main content

The component manager for ESP-IDF

Project description

IDF Component Manager

The IDF Component manager is a tool that downloads dependencies for any ESP-IDF CMake project. It makes sure that the right versions of all components required for a successful build of your project are in place. The download happens automatically during a run of CMake. It can source components either from the component registry or from a git repository.

A list of components can be found at

Installing the IDF Component Manager

IDF component manager can be used with ESP-IDF v4.1 and later. It is installed by default with ESP-IDF v4.4+ and recent bug-fix releases of ESP-IDF 4.1+.

To check the installed version of the IDF component manager, first, activate ESP-IDF environment. On macOS and Linux:

source $IDF_PATH/

Then run the command:

python -m idf_component_manager -h

To update to the most recent version:

pip install idf-component-manager --upgrade

Disabling the Component Manager

The component manager can be explicitly disabled by setting IDF_COMPONENT_MANAGER environment variable to 0.

Using with a project

You can add idf_component.yml manifest files with the list of dependencies to any component in your project.

IDF Component Manager will download dependencies automatically during the project build process.

When CMake configures the project (e.g. reconfigure) component manager does a few things:

  • Processes idf_component.yml manifests for every component in the project
  • Creates a dependencies.lock file in the root of the project with a full list of dependencies
  • Downloads all dependencies to the managed_components directory

The component manager won't try to regenerate dependencies.lock or download any components if manifests, lock file, and content of managed_component directory weren't modified since the last successful build.

Defining dependencies in the manifest

All dependencies are defined in the manifest file.

  # Required IDF version
  idf: ">=4.1"
  # For components maintained by Espressif only name can be used.
  # Same as `espressif/component`
    version: "~2.0.0"
  # Or in a shorter form
  component2: ">=1.0.0"
  # For 3rd party components :
    version: "~1.0.0"
    # For transient dependencies `public` flag can be set.
    public: true
  anotheruser/component: "<3.2.20"
  # For components hosted on non-default registry:
    version: "~1.0.0"
    service_url: ""
  # For components in git repository:
    path: test_component
    git: ssh://
  # For test projects during component development
  # components can be used from a local directory
  # with relative or absolute path
    path: ../../projects/component
  # For optional dependencies
    version: "~1.0.0"
    rules: # will add "optional_component" only when all if clauses are True
      - if: "idf_version >=3.3,<5.0" # supports all SimpleSpec grammars (
      - if: "target in [esp32, esp32c3]" # supports boolean operator ==, !=, in, not in.
  # For example of the component
    version: "~1.0.0" # if there is no `override_path` field, use component from registry
    override_path: "../../" # use component in a local directory, not from registry
    version: "*"
    require: no # Download component but don't add it as a requirement
    version: "*"
    pre_release: true # Allow downloading of pre-release versions

Environment variables in manifest

You can use environment variables in values in idf_component.yml manifests. $VAR or ${VAR} is replaced with the value of the VAR environment variable. If the environment variable is not defined, the component manager will raise an error.

Variable name should be ASCII alphanumeric string (including underscores) and start with an underscore or ASCII letter. The first non-identifier character after the $ terminates this placeholder specification. You can escape $ with one more$ character, i.e., $$ is replaced with $.

One possible use-case is providing authentication to git repositories accessed through HTTPS:

    git: https://git:${ACCESS_TOKEN}

Component metadata caching

By default information about available versions of components is cached for 5 minutes. You can adjust caching period by setting the duration in minutes to IDF_COMPONENT_API_CACHE_EXPIRATION_MINUTES environment variable or disable the cache entirely by setting it to 0.

External links

You can add links to the idf_component.yml file to the root of the manifest:

url: "" # URL of the component homepage
repository: "" # URL of the public repository with component source code, i.e GitHub, GitLab, etc.
documentation: "" # URL of the component documentation
issues: "" # URL of the issue tracker
discussion: "" # URL of the component discussion, i.e. Discord, Gitter, forum, etc.

A link should be a correct HTTP(S) URL like except the repository field, it is expected to be a valid Git remote URL.

Add examples to the component

To add examples to your component place them in the examples directory inside your component. Examples are discovered recursively in subdirectories at this path. A directory with CMakeLists.txt that registers a project is considered as an example.

Custom example paths

You can specify custom example paths for uploading them to the component registry. For that, add examples field to the root of the manifest:

  - path: ../some/path
  - path: ../some/other_path

Environment variables

Variable Default value (or example for required) Required? Description
IDF_COMPONENT_API_TOKEN no API token to access the component registry
IDF_COMPONENT_REGISTRY_URL no URL of the default component registry
IDF_COMPONENT_STORAGE_URL no URL of the default file storage server
IDF_COMPONENT_REGISTRY_PROFILE default no Profile in the config file to use for component registry
IDF_COMPONENT_API_CACHE_EXPIRATION_MINUTES 5 no API Cache expiration time in minutes
IDF_COMPONENT_CACHE_PATH * Depends on OS no Cache directory for component manager
COMPONENT_MANAGER_JOB_TIMEOUT 300 no Timeout in seconds to wait for component processing
IDF_COMPONENT_OVERWRITE_MANAGED_COMPONENTS 0 no Overwrite files in the managed_component directory, even if they have been modified by the user
IGNORE_UNKNOWN_FILES_FOR_MANAGED_COMPONENTS 0 no Ignore unknown files in managed_components directory

Contributions Guide

We welcome all contributions to the Component Manager project.

You can contribute by fixing bugs, adding features, adding documentation, or reporting an issue. We accept contributions via Github Pull Requests.

Before reporting an issue, make sure you've searched for a similar one that was already created. If you are reporting a new issue, please follow the Issue Template.

Installing a development version of the component manager

You can install the development version of the component manager from the main branch of this repository:

On Linux/macOS:

Go to the directory with your ESP-IDF installation and run:

# activate ESP-IDF environment
source ./ # or . ./, if you use fish shell
# remove old version of the component manager
python -m pip uninstall -y idf-component-manager
# install the development version (from the main branch)
python -m pip install git+

On Windows:

Run ESP-IDF PowerShell Environment or ESP-IDF Command Prompt (cmd.exe) from the Start menu and run the following command:

# remove old version of the component manager
python -m pip uninstall -y idf-component-manager
# install the development version (from the main branch)
python -m pip install git+


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

idf_component_manager-1.3.0.dev0.tar.gz (95.2 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page