How to Install HACS on Home Assistant: Setup Guide

This post may contain affiliate links. As an Amazon Associate we earn from qualifying purchases. Disclosure.

HACS opens Home Assistant to community integrations, custom dashboard cards, themes, and Python scripts that the official integration list never ships. This step-by-step setup guide follows the current HACS documentation, so the commands and screens below match what the project describes today rather than an old forum recipe.

This guide is built from the HACS documentation rather than from a log of my own installs, so check each step against the current docs if something on your screen looks different. The process below applies to current Home Assistant releases.

One opinion I'll stand behind: HACS should ship inside Home Assistant by default, and the fact that it doesn't is the project's most baffling call. Plenty of useful hardware support lives only in community repositories. Install it early and stop pretending it's optional.

Why You Want HACS Before You Want It

The built-in integration list is curated. Core integrations go through review by Home Assistant maintainers, and the Home Assistant quality scale grades how well each one is built. The result is reliable but limited: it covers the major vendors and protocols, and new hardware often takes a while to arrive.

Community code fills the gap. A new gadget may have a maintained integration on GitHub months before it lands in core, a dashboard card library may never be considered for core at all, and a niche device may only ever be supported by a hobbyist. HACS makes all of that browsable in one place.

HACS bridges the gap. It is, effectively, the npm of Home Assistant. Once installed it adds a HACS section to the sidebar with search, filters by repository type, version selection and one-click updates.

What You Need Before Starting

Three prerequisites, per the HACS documentation:

• A running Home Assistant 2024.4.1 or newer on a supported install type (Home Assistant OS, Supervised, Container or Core)
• Access to the file system of the installation, plus some comfort with reading logs
• A free GitHub account, and an internet connection that doesn't block outgoing requests to GitHub

The download method depends on your install type. Home Assistant OS and Supervised use an add-on, while Container and Core run a download script. HACS itself isn't an add-on, even though an add-on is the delivery vehicle on those installs.

Step 1: Download HACS

On Home Assistant OS or Supervised, open the add-on store, add the repository https://github.com/hacs/addons through the menu, install the add-on called Get HACS, start it, and follow what its log tells you. Newer Home Assistant releases call add-ons "apps", but it is the same menu.

On Container installs, open a terminal, enter the container with docker exec, and run the script below. On Core, switch to the Home Assistant user account first and run the same script.

wget -O - https://get.hacs.xyz | bash -

The script downloads the HACS files from GitHub and places them in the custom_components directory. It is published by the HACS maintainers and described in the HACS docs. Read it before running it if you want to verify what gets installed.

Step 2: Restart Home Assistant

The custom_components directory only loads at startup, so restart Home Assistant after the download. Watch the logs (Settings, System, Logs) during the restart. Errors mentioning HACS at this stage usually point at the files not being where Home Assistant expects them, so check that /config/custom_components/hacs exists and has files in it.

Step 3: Add HACS as an Integration

After the restart, go to Settings, Devices & Services, Add Integration, and search for "HACS". The wizard asks you to acknowledge a list of statements, then starts the GitHub sign-in.

HACS uses GitHub's device authorization flow, not a personal access token. The wizard shows a code. Open https://github.com/login/device in a browser, sign in to GitHub if you aren't already, enter the code, continue, and select Authorize HACS. Back in Home Assistant, assign HACS to an area and finish. Treat the authorization like any other connected app on your GitHub account: you can review and revoke it in your GitHub settings later.

What to Install First (And What to Avoid)

The temptation after installing HACS is to add a pile of packages immediately. Don't. The HACS ecosystem includes some genuinely excellent packages and some abandoned hobby projects, and mixing the two creates instability that takes ages to debug.

Open HACS from the sidebar, search, open a repository to read its README, and select Download. By default you get the newest version, and you can pick an older one if your Home Assistant version needs it. Repositories that show a pending restart status only become active after you restart Home Assistant.

Three categories worth starting with:

Dashboard card libraries: Mushroom Cards, button-card, Bar Card. These transform the default Home Assistant dashboard from functional to elegant. None of them affect device behaviour, so the worst case is a broken card you remove.

Hardware-specific integrations: Hardware that Home Assistant does not yet support officially often has a maintained community integration. Check the repository for recent commits and active issues before installing.

Themes: Pure visual changes with no risk to the underlying integrations.

Two categories to approach carefully:

AppDaemon apps: These run Python code with full Home Assistant access. A bad AppDaemon app can crash the entire install. Read the source before installing anything in this category.

Python scripts: Similar risk profile to AppDaemon. Prefer packages with clear documentation and recent maintenance, or write your own scripts using the official Python script integration with limited scope.

Update Discipline Keeps HACS Stable

The biggest long-term risk with HACS is update fatigue. The HACS UI shows updates for every installed package, and clicking through all of them at once can break things. Treat HACS updates like upgrading any package manager:

• Read the changelog before updating
• Update one package at a time
• Restart Home Assistant after each update that asks for it
• Verify the dashboard still works before moving to the next
• Roll back by downloading an earlier version of the repository if something breaks

The release notes for community packages vary from excellent to non-existent. For packages with poor changelogs, lurk in the GitHub issues for a few days after a new release before updating to check whether anyone has reported breakage.

HACS gives Home Assistant the flexibility that the official integration list deliberately constrains. The cost is a small ongoing maintenance overhead. For most homes the trade-off is positive, but it only holds if you keep the habit of reading before you click.

Common Setup Problems and How to Fix Them

Four problems come up again and again in fresh HACS installs, and each has a plain explanation.

"HACS integration not found in search" after the restart usually means the custom_components directory does not contain the HACS folder. Check via a terminal that ls /config/custom_components/hacs lists files. If the directory is missing, rerun the download method for your install type. On Container installs, make sure you ran it inside the container and that the folder is on a persistent volume.

The GitHub sign-in never completes usually means the device code expired or the browser tab sat idle. Close the HACS setup dialog, start it again to get a fresh code, and enter it promptly at github.com/login/device.

HACS loads but no repositories appear is almost always a network problem with GitHub. The HACS prerequisites require that outgoing requests to GitHub and Cloudflare are not blocked, so check firewall rules, DNS filtering and any proxy before you suspect HACS itself.

A custom integration won't install or load after a Home Assistant update often means the package needs a different Home Assistant version than yours. Open the repository on GitHub, read the README for the minimum version, and pick a compatible release from the version list in HACS. Downgrading Home Assistant Core is not a good fix.

What HACS Does Not Solve

For honesty: HACS is a package manager, not a magic wand. It does not validate that a community integration is secure, well-written, or maintained. It does not test that a Lovelace card works in your specific dashboard. It does not guarantee that an integration will keep working after the next Home Assistant Core release.

What HACS actually does is reduce the friction of installing community packages from a manual git-clone-and-restart workflow to a one-click UI. The reduced friction is worth a lot in practice, but it does not replace the judgement of evaluating each package on its own merits before adding it to a production system.

Treat HACS like an app store with no review process. Just because something is listed does not make it good. The package metadata (stars, last commit, open issues) is your only filter, so check it every time. Take a backup before you add your first package, too, so a bad install is a restore rather than a rebuild. Our roundup of the best HACS integrations is a shorter place to start.