You can easily import community or personal components using the external components feature. Bundled components can be overridden using this feature.
You can find some basic documentation on creating your own components at Contributing to ESPHome.
external_components: # use rtttl and dfplayer from ESPHome's dev branch in GitHub - source: type: git url: https://github.com/esphome/esphome ref: dev components: [ rtttl, dfplayer ] # equivalent shorthand for GitHub - source: github://esphome/esphome@dev components: [ rtttl ] # equivalent shorthand for GitHub pull request - source: github://pr#2639 components: [ rtttl ] # use all components from a local folder - source: type: local path: my_components
type (Required): Repository type. One of
url (Required, url): HTTP git repository url. See Git.
ref (Optional, string): Git ref (branch or tag). If not specified the default branch is used.
username (Optional, string): Username for the Git server, if one is required
password (Optional, string): Password for the Git server, if one is required
path (Required): Path to use when using local components. See Local.
components (Optional, list): The list of components to use from the external source. By default, all available components are used.
You can specify a local path containing external components. This is most useful when developing a component or if you want to manually control the origin of the files.
external_components: - source: path: /copied_components # shorthand external_components: - source: my_components
Notice that relative paths are supported, so you can enter
my_components as the source path and then
ESPHome will load components from a
my_components folder in the same folder where your YAML configuration
Example of local components¶
Given the above example of
my_components, the folder structure must look like:
<CONFIG_DIR> ├── node1.yaml ├── node2.yaml └── my_components ├── my_component1 │ ├── __init__.py │ ├── component1.cpp │ ├── component1.h │ └── sensor.py └── my_component2 ├── __init__.py ├── component2.cpp ├── component2.h └── switch.py
Retrieving components from git is the easiest way to use components not included in ESPHome by default.
The source components should be inside a
components folder or inside an
folder. The latter makes sharing a component from a forked ESPHome repository easier.
Example of git repositories¶
For repositories where you share one or a few components:
components ├── my_component1 │ ├── __init__.py │ ├── component1.cpp │ ├── component1.h │ └── sensor.py └── my_component2 ├── __init__.py ├── component2.cpp ├── component2.h └── switch.py example_component1.yaml <- not required but recommended README.md
or, this structure is also supported, which makes handy to share components from a forked ESPHome repository:
esphome ├── components │ ├── my_component1 │ │ ├── __init__.py │ │ ├── component1.cpp │ │ ├── component1.h │ │ └── sensor.py │ ├── my_component2 │ │ ├── __init__.py │ │ ├── component2.cpp │ │ ├── component2.h │ │ └── switch.py │ ... ...
HTTP git repositories in general are supported with this configuration:
external_components: source: type: git url: http://repository_url/ ref: branch_or_tag
The source field accepts a short hand github:// resource:
external_components: # shorthand source: github://<user or org>/<repository name>[@<branch or tag>]
The source field also accepts a short hand github:// pull request from the ESPHome repository:
external_components: # shorthand source: github://pr#<number>
Under the hood, during validation, ESPHome will clone the git repository into the hidden
folder and components will then be loaded from this local copy. The local path of the cloned repository
varies per repository name and ref name, so repositories with different refs are considered different
repositories and updated independently.
If required, you can supply a username and password to use when authenticating with the remote git
server using the
password fields. This is most useful when combined with the
!secret feature, to load the values in from a
secrets.yaml file. This is not a comprehensive
security measure; your username and password will necessarily be stored in clear text within the
Components are initially cloned into a cache directory, then the repository is checked for updates
(via git pull) after the
refresh: time passes since last check.
You can make ESPHome check the repository every time by setting this option to
0s, however since
ESPHome is validating the configuration continuously while using the dashboard or the vscode extension,
it is not recommended to set this value to less than a few minutes to avoid validation slow down and
excessive repository checks.
Likewise, you can set this setting to
never and ESPHome will never
update the repository, useful e.g. when
ref points to a tag.