How to Install HACS on Home Assistant: Full Setup Walkthrough

Home Assistant Raspberry Pi Troubleshooting ZigBee Apple HomeKit

HACS opens Home Assistant to 2000-plus community integrations, custom Lovelace cards, themes, and Python scripts that the official add-on store never ships. Installing it takes ten minutes the first time and never again. This step-by-step setup guide walks through the exact walkthrough I run on every fresh Home Assistant install.

I installed HACS on my own Home Assistant for the first time in 2019 and have repeated the process on roughly twelve fresh installs since then -- friends, family, two AirBnBs, a small consulting client. The five-step process below works in 2026 with current Home Assistant Core releases.

Why You Want HACS Before You Want It

The Home Assistant official add-on store is curated. Maintainers review submissions against the Home Assistant quality scale and reject anything that does not meet the bar. The result is reliable but limited -- roughly 200 integrations covering the major vendors and protocols.

Most homes need more. The Aqara M3 hub I bought last year wasn't supported in the official store for six months. The custom Zigbee2MQTT converter I wrote for a wine fridge sensor is HACS-only and will probably stay that way. The Mushroom Lovelace card library that transforms dashboard aesthetics has never been in the official store at all.

HACS bridges the gap. It is, effectively, the npm of Home Assistant. Once installed it adds a Community section alongside the official store with categorised browsing, version pinning, and one-click updates.

What You Need Before Starting

Three prerequisites:

  • A running Home Assistant install (Home Assistant OS, Container, Supervised, or Core)
  • SSH or web terminal access to the Home Assistant filesystem
  • A free GitHub account

The official add-on installer requires Home Assistant OS or Supervised. Container and Core installs need a manual installer that runs over SSH and copies the HACS files into the custom_components directory.

Step 1: Generate a GitHub Personal Access Token

HACS authenticates against the GitHub API to fetch package metadata and respect rate limits. Without authentication you'd hit the unauthenticated rate limit (60 requests per hour) within a few minutes of browsing packages.

Go to GitHub Settings, Developer Settings, Personal Access Tokens. Create a fine-grained token with the scope "public_repo (read only)" and a 1-year expiration. Copy the token; you'll paste it in step 5. Treat the token like a password -- it grants HACS the same read access you'd have logged in.

For households running multiple Home Assistant installs (a primary and a backup, or one per family member), create a separate token per install so you can revoke one without affecting the others.

Step 2: Install the Terminal and SSH Add-on

Home Assistant OS and Supervised users go to Settings, Add-ons, Add-on Store, search for "Terminal & SSH", install. Enable the "Show in sidebar" toggle for quick access. Start the add-on.

The official Terminal & SSH add-on is the safer choice for HACS install because it runs as the Home Assistant user with the right paths preconfigured. The community SSH add-on works too but has subtly different path expectations that occasionally break the HACS installer.

Container and Core users can skip this step and use any SSH client to log into the Home Assistant host directly.

Step 3: Run the HACS Installer Script

Open the terminal and run:

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

The installer downloads the HACS files from GitHub, places them in the correct custom_components directory, and prints a confirmation. The script is published by the HACS maintainers and reviewed in the HACS docs -- read it before running if you want to verify what gets installed.

The script takes about 30 seconds to complete on a Raspberry Pi 5 and under 10 seconds on a beefier mini PC. Network speed matters more than CPU here because the download is a few hundred MB.

Step 4: Restart Home Assistant Core

The custom_components directory only loads at startup. Go to Settings, System, Restart Home Assistant Core. The restart takes 30-90 seconds depending on the size of your existing integration list.

Watch the logs (Settings, System, Logs) during the restart. Errors mentioning HACS at this stage usually mean the installer script didn't have write permission to the custom_components directory -- rerun with sudo on Container or Core installs.

Step 5: Add HACS as an Integration

After the restart, go to Settings, Devices & Services, Add Integration, search for "HACS". The integration wizard asks for the GitHub personal access token from step 1. Paste it. The wizard then takes you through an experimental-features confirmation (the four toggles: integrations, plugins, themes, AppDaemon -- check all four unless you have a strong reason not to).

The first sync after enabling HACS downloads category indices and can take 5-10 minutes. The status appears in Settings, Devices & Services, HACS. After the first sync, browse categories from the new HACS section in the sidebar.

What to Install First (And What to Avoid)

The temptation after installing HACS is to add 20 packages immediately. Don't. The HACS ecosystem includes some genuinely excellent packages and some abandoned hobby projects. Mixing the two creates instability that takes weeks to debug.

Three categories worth starting with:

Lovelace 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.

Vendor-specific integrations: Hardware that Home Assistant does not yet support officially often has a maintained HACS integration. Aqara M3, SwitchBot cloud devices, certain Mi Home products. Check the package's GitHub for recent commits and active issues before installing.

Quality-of-life themes: Caule Themes, Material 3 Theme, Graphite Theme. 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.

Custom Python scripts: Similar risk profile to AppDaemon. Stick to packages with 200+ stars and clear documentation, or write your own scripts using the official Python script integration with limited scope.

Five Most Useful HACS Packages I Run

The exact packages running on my own Home Assistant in 2026:

  1. mushroom-cards by piitaya -- the dashboard card library every modern HA install uses
  2. lovelace-mod-card -- enables CSS overrides for any card, fixing visual inconsistencies
  3. zigbee2mqtt-edge -- bleeding-edge Z2M for early Zigbee device support
  4. alexa_media_player -- proper Alexa device control beyond what the official Amazon integration offers
  5. browser_mod -- dashboard popups and per-browser conditional rendering

Each one has 1000+ stars, active maintenance, and runs without issue in my install for over a year. The combination delivers daily-use value -- not just installed-and-forgotten packages.

Update Discipline Keeps HACS Stable

The biggest long-term risk with HACS is update fatigue. The HACS UI shows updates for every installed package; clicking "update all" 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
  • Verify the dashboard still works before moving to the next
  • Roll back via the version dropdown 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 store deliberately constrains. The cost is a small ongoing maintenance overhead. For most homes the trade-off is overwhelmingly positive -- HACS is the difference between a smart home that does what you imagined and one limited to what the core team has officially approved.

Common Setup Errors and How to Fix Them

Five recurring errors I see in fresh HACS installs and the fixes that work consistently.

"HACS integration not found in search" after the restart usually means the custom_components directory does not contain the HACS folder. Check via Terminal: ls /config/custom_components/hacs should list files. If the directory is missing, rerun the installer script with proper write permissions. On Container installs this often requires running the installer as the same user the Home Assistant container runs under.

"GitHub authentication failed" during step 5 means the personal access token is wrong, expired, or has the wrong scope. Regenerate with explicit public_repo read access on classic tokens or Contents: read-only on fine-grained tokens. Paste the new token immediately into HACS without saving it elsewhere -- some users save the token in a notes app and lose track of which version is current.

"HACS Settings page loads but no categories appear" is almost always a network problem with GitHub. Wait 10 minutes for the first sync, then check the HACS log via Settings → System → Logs and filter for "hacs". The first sync downloads several MB of category indices; slow connections may need 20-30 minutes.

"Custom integration says it requires HACS but won't install" usually means the version pin is incompatible with your Home Assistant Core version. Check the integration's GitHub repo for the minimum Core version stated in the README. Older HACS packages may require Home Assistant Core 2024.4 or later; downgrading HA Core is not a good fix, but you can usually find a compatible older release of the package.

"After updating HACS itself, integrations break" is the worst category of error because it can affect multiple devices at once. Always restart Home Assistant Core after a HACS self-update, not before. The HACS update process needs the restart to load the new package manifests cleanly. If integrations still break, restore from the snapshot Home Assistant took before the restart (Settings → System → Backups).

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.

View full version