How to Configure the IDF Component Manager

This page shows common configuration tasks: choosing a registry, improving download speeds, and using a local mirror.

The Component Manager reads settings from the idf_component_manager.yml configuration file (profiles), and you can override selected settings with environment variables.

For the complete configuration file schema and field semantics, see idf_component_manager.yml Configuration File.

Common scenarios

Use the default registry

If you do not need any customization, you can rely on the defaults (the public ESP Component Registry). A minimal configuration looks like:

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

Improve download speeds in China (storage_url)

If you are located in China, you can configure an alternative storage endpoint to speed up component downloads:

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

Use a local mirror or offline storage (local_storage_url)

If you have created a local mirror (see How to Create and Use Partial Mirror), set local_storage_url so the solver checks your mirror first:

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

Environment variables (overrides)

Environment variables have higher precedence than the configuration file. Use them as temporary overrides (for example, in CI), or when you cannot edit the configuration file.

class idf_component_tools.environment.ComponentManagerEnvVariables

Component Manager settings.

Warning

For environment variable aliases, the first alias is the recommended one. Any other listed aliases are also supported, but deprecated and will raise a UserDeprecationWarning if they are set in the environment. They may be removed in the future.

attribute IDF_COMPONENT_API_TIMEOUT: float | None = None
Timeout for API requests to the Component Registry in seconds.
If not set, the default timeout of the HTTP client will be used.

Aliases:

  • IDF_COMPONENT_API_TIMEOUT

  • IDF_COMPONENT_SERVICE_TIMEOUT (deprecated)

attribute IDF_COMPONENT_API_TOKEN: str | None = None

API token to access the Component Registry.

attribute IDF_COMPONENT_CACHE_HTTP_REQUESTS: bool = True
Cache HTTP requests to the Component Registry during runtime.
Set 0 to disable.
attribute IDF_COMPONENT_CACHE_PATH: str | None = None
Cache directory for Component Manager.
Default: Depends on OS
attribute IDF_COMPONENT_CHECK_NEW_VERSION: bool = True

Check for new versions of components.

attribute IDF_COMPONENT_CONSTRAINTS: str | None = None
Direct constraint definitions for component version solving.
To specify multiple constraints, use semicolons to separate them:
namespace/component_name>=version;component_name>=version;...
attribute IDF_COMPONENT_CONSTRAINT_FILES: str | None = None
Constraint files for component version solving.
To specify multiple files, use semicolons to separate them:
/path/to/file1;/path/to/file2,...
attribute IDF_COMPONENT_DEBUG_MODE: bool = False

Enable debug mode.

attribute IDF_COMPONENT_LOCAL_STORAGE_URL: str | None = None
URL of the mirror.
To set multiple URLs, use semicolon (;) to separate them:
<url1>;<url2>;...
attribute IDF_COMPONENT_NO_COLORS: bool = False

Disable colored output.

attribute IDF_COMPONENT_NO_HINTS: bool = False

Disable hints in the output.

attribute IDF_COMPONENT_OVERWRITE_MANAGED_COMPONENTS: bool = False
Overwrite files in the managed_components directory,
even if they have been modified by the user.
attribute IDF_COMPONENT_PROFILE: str | None = None
Profile in the config file to use.
Default: default

Aliases:

  • IDF_COMPONENT_PROFILE

  • IDF_COMPONENT_REGISTRY_PROFILE (deprecated)

  • IDF_COMPONENT_SERVICE_PROFILE (deprecated)

attribute IDF_COMPONENT_REGISTRY_URL: str | None = None
URL of the default Component Registry.
Default: https://components.espressif.com/

Aliases:

  • IDF_COMPONENT_REGISTRY_URL

  • DEFAULT_COMPONENT_SERVICE_URL (deprecated)

attribute IDF_COMPONENT_STORAGE_URL: str | None = None
URL of the file storage server.
To set multiple URLs, use semicolon (;) to separate them:
<url1>;<url2>;...
Default: https://components-file.espressif.com/
attribute IDF_COMPONENT_STRICT_CHECKSUM: bool = False
Validate checksums strictly.
If set to 1, checksum of each file will be compared to the expected value.
attribute IDF_COMPONENT_SUPPRESS_UNKNOWN_FILE_WARNINGS: bool = False

Ignore unknown files in managed_components directory.

Aliases:

  • IDF_COMPONENT_SUPPRESS_UNKNOWN_FILE_WARNINGS

  • IGNORE_UNKNOWN_FILES_FOR_MANAGED_COMPONENTS (deprecated)

attribute IDF_COMPONENT_VERIFY_SSL: bool | str = True
Verify SSL certificates when making requests to the Component Registry.
Set 0 to disable or provide a CA bundle path.
attribute IDF_COMPONENT_VERSION_PROCESS_TIMEOUT: int = 300

Timeout for processing version jobs in seconds.

Aliases:

  • IDF_COMPONENT_VERSION_PROCESS_TIMEOUT

  • COMPONENT_MANAGER_JOB_TIMEOUT (deprecated)