Using the HACS dashboard

This section shows you how to use the HACS dashboard.

Browsing repositories

1. To open HACS, in the Home Assistant sidebar, select the HACS icon.
   • Each line in the data table represents a community repository that can be downloaded via HACS.
2. To browse the repositories, use the search and filter functions.
   • The HACS dashboard uses the same table features used elsewhere in Home Assistant.
   • By default, the dashboard shows the repositories you have downloaded with HACS on top of the list.
3. To view the repository documentation, select the 3 dots menu, then select Show details.
   • To view the source code, select Repository.
4. Once you have found the custom element you want to use in Home Assistant, download the repository.

Search repositories

You can search for both downloaded and available repositories in HACS.

1. Enter your search term in the search field.

2. The search is not limited to the repository name or description. You can search for data from different categories, including:

   • Author
   • Type
   • Description
   • Name
   • Status
   • Topics

   

Filtering repositories

1. To define filters, next to the searchbar, select the () Filters button.

   2. There are currently 2 filter types, Type and Status:

   • Type: filters for a specific type of custom element: integration, dashboard, theme, template, AppDaemon app, or Python Script.

   • Status:

     • Pending update: There is a new version available for this repository. To download it, select Redownload.
     • Pending restart: The repository has been downloaded. But for the software version to become active, you need to restart Home Assistant.
       • Repositories with a pending restart generate a repair issue under System > Updates. You can restart directly from there.
     • New: HACS found repositories it has not seen before. If you select Dismiss new, these will be shown under Available for download.
     • Downloaded: The repository has been downloaded. You can use its functionality.
     • Available for download: This is a repository that is not new to HACS and that you can download.

     

2. Troubleshooting: Don't see the status or type in your table?

   • Make sure the columns are not hidden.

Updating repository metadata

HACS regularly checks the repositories for updates and imports the new metadata, if there were changes. The metadata is what HACS knows about this repository. For example: the description, the documentation, the version information. In general, you do not need to check for updates. It is done automatically. But if you want to check immediately, you can manually trigger an update of the repository data.

1. In Home Assistant, open HACS and find the repository of interest.
2. On the repository entry, select the 3 dots menu, then select Update information.

   • Result: If there were changes, the repository metadata is updated.

     • You can now make an informed decision whether you want to download the new software version of the repository (if there even was a new version).

     Update information does not change the downloaded repository content

     Update information only updates what HACS knows about this repository. To get the new software version, you need to download it.

Downloading a repository

To use the functionality provided by a repository, you need to download it to Home Assistant.

1. In Home Assistant, open HACS and find the repository of interest.

2. Select the repository and view its overview page.

   • The main section of this view renders the README file of the repository.
   • The badges on top provide some key information, such as author, GitHub stars, and the number of open issues and pull requests.
     • This page should also contain the documentation on how to use it.
     • The content depends on the repository type and on the information the author provides.

   

3. To download the repository, in the bottom-right corner, select the Download button.

   • This opens a dialog that lets you download the repository.
   • By default, the newest version is downloaded. If needed, you can select a specific version.
     • A reason to choose an older version would be if you run an older version of Home Assistant and the newer version of the repository requires a newer version of Home Assistant.
     • Check the documentation of the repository to find out which version of Home Assistant is required.
     • If you need a different version, under Need a different version?, select the version you want to download.
   • Troubleshooting: Don't see the Download button? The button doesn't show if the repository has already been downloaded.

Downloading a specific version of a repository

By default, the newest version of a repository is downloaded. If needed, you can select a specific version.

• A reason to choose an older version would be if you run an older version of Home Assistant and the newer version of the repository requires a newer version of Home Assistant.
• Check the documentation of the repository to find out which version of Home Assistant is required.

To download a specific version, follow these steps:

1. In Home Assistant, open HACS and find the repository of interest.
2. On the repository entry, select the 3 dots menu, then select the available option:
   • Download, if the repository has not been downloaded yet.
   • Redownload, if the repository has been downloaded previously.
3. Under Need a different version?, select the version you want to download.
   • Troubleshooting: Don't see a version selector? Not all repositories support versioning.

Removing a repository

1. In Home Assistant, open HACS and find the repository you want to remove.
2. On the repository entry, select the 3 dots menu, then select Remove.
   • This removes the repository that was stored in your Home Assistant configuration directory.
3. Removing the repository does not remove the related data. Check the documentation of the repository for instructions on how to remove it.

Reporting an issue with a repository

If you're experiencing an issue with a particular custom element, always report the issue to the repository owner, not to HACS or Home Assistant.

1. On the repository entry, select the 3 dots menu, then select Open issue.
   • This opens the issue tracker of the GitHub repository for that custom element.
2. To open an issue, in their repository, select New issue.
3. Add a detailed description of your issue and submit.

Using the HACS Menu

At the top-right corner, you will find the 3 dots () menu.

Here you can:

• Open the documentation of HACS itself
• Open the GitHub page of HACS itself.
• Open an issue for HACS itself.
• Add custom repositories.
• Dismiss all new repositories (if you have any).
• Show information about your HACS installation.

Dismissing new repositories

Any addition to HACS that you have not yet seen will show the status New. If you are sorting by status, they will show on top by default. If you want, you can dismiss these, so that they are no longer shown as new. This is similar to marking emails as read in your inbox.

---

Help and support

Resources

Code of Conduct

Contact (no support!)

Made with Material for MkDocs

Help us make these docs great!

All HACS docs are open source. See something that's wrong or unclear? Submit a pull request.

Edit this page on GitHub
_{Learn how to contribute}

Still need help?

• Create an issue
• Join the Discord server