idf_component_manager.yml Configuration File

The IDF Component Manager configuration file, named idf_component_manager.yml, is a YAML file that defines a set of profiles. Each profile is a collection of configurations that determines where components are uploaded from or downloaded to.

By default, the configuration file is located in the following paths:

WindowsUnix-like

C:/Users/YOUR_USERNAME/.espressif

You can also override the path by setting the IDF_TOOLS_PATH environment variable.

Configuration File

Added in version 2.1: Support for local storage mirrors and the local_storage_url field.

Each profile supports the following URL-related fields:

Field	registry_url	storage_url	local_storage_url
Type	URI	URI or list of URIs	URI or list of URIs
Default	components.espressif.com	None	None
Override by Environment Variable?	IDF_COMPONENT_REGISTRY_URL	IDF_COMPONENT_STORAGE_URL	❌
Supports Upload?	✅	❌	❌
Supports Download?	✅	✅	✅
Requires Internet?	✅	✅	❌

In addition to URLs, each profile supports the following fields:

Field	Type	Default	Description	Required?
api_token	string	None	The API token used to authenticate with the registry_url.	Required for uploading components.
default_namespace	string	espressif	The default namespace for uploading components.	❌

Here is a minimal default configuration:

profiles:
  default:
    registry_url: "components.espressif.com"

For users in China, we recommend using the following storage_url to improve download speeds:

profiles:
  default:
    storage_url:
      - "https://components-file.espressif.cn"

If you have a local mirror set, you can also define the local_storage_url in the configuration file:

profiles:
  default:
    local_storage_url:
      - file:///Users/username/storage/  # Unix path
      # - file://C:/storage/             # Windows path
      - http://localhost:9004

URL Precedence During Version Solving

When solving versions, the resolver checks sources in the following order:

1. local_storage_url

2. storage_url

3. registry_url

If a valid version is found in one of the earlier sources, the resolver does not check the remaining ones. If no source provides a valid version, an error is returned.

Given the following configuration:

profiles:
  default:
    registry_url: a.com
    storage_url:
      - b.com
      - c.com
    local_storage_url:
      - http://localhost:9004
      - http://localhost:9005

The version solver will check sources in this order:

• registry_url defined in the manifest dependencies field

• http://localhost:9004

• http://localhost:9005

• b.com

• c.com

• a.com

Login via CLI

The api_token and default_namespace fields are populated automatically when you log in via the CLI. For login instructions (both production and staging), see How to Authenticate for Publishing.