What HACS Does
HACS extends Home Assistant beyond the official integration catalog by giving you a UI to discover, install, and manage community repositories. It handles three element types:
- Integrations — Python-based custom components that add new device support, services, or automations.
- Frontend — Lovelace cards and plugins that enhance the Home Assistant dashboard.
- Themes — Visual themes applied through Home Assistant's frontend settings.
HACS itself runs as a custom integration inside Home Assistant. Once installed, it appears in the sidebar and stays connected to GitHub to track repository versions.
Before You Install HACS
HACS requires three things before you start:
- A GitHub account. HACS uses GitHub OAuth to fetch data. Create one at github.com first.
- A supported Home Assistant installation. OS, Supervised, and Container support standard methods. Core requires manual file copying.
- Outbound internet access. Your host must reach
github.comandraw.githubusercontent.comon port 443.
Installing HACS: Step by Step
Short answer: Run the official HACS downloader script in a terminal, restart HA, and add the integration from Settings.
Open a terminal
On Home Assistant OS or Supervised, use the Terminal & SSH add-on. On Container, SSH directly into your host.
Run the downloader
Copy the command from hacs.xyz. The script places HACS in your custom_components directory.
Restart Home Assistant
A full restart is required (Settings → System → Restart). A config reload is not enough.
Add Integration
Go to Settings → Integrations → Add Integration, search for "HACS".
Authorize GitHub
Enter the device code shown on GitHub's authorization page to link your account.
Common HACS Errors
"Unknown error" when adding the integration
Usually means the restart was incomplete. Confirm the custom_components/hacs folder exists and perform a full restart.
GitHub rate limit error
GitHub's limits reset after one hour. Wait and try again, or check for other network services using GitHub API.
Network errors or "can't connect"
Confirm outbound HTTPS access on port 443. Check firewall rules and DNS resolution on your host.
Frequently Asked Questions
Does HACS work with Home Assistant Core?
Yes, but the script needs shell access. On bare-Python Core, copy files manually into custom_components following HACS.xyz.
What is the difference between HACS and official integrations?
Official integrations are reviewed by the HA core team. HACS integrations are community-maintained; quality and maintenance frequency vary.
Can HACS install add-ons?
No. HACS manages integrations, cards, and themes. Add-ons are separate Docker containers installed through the official Add-on Store.