How to manually remove an orphaned repo from HACS in HomeAssistant

I recently wanted to add a new repo to Home Assistant using HACS (specifically, ha-sun2, so I could take a stab at automating my roller shades to open without blinding me in the morning while I’m still in bed). In HACS, there’s a “Custom Repositories” option which allows you to add repositories from Github and install them automagically.

In my case, the option was greyed out. There are a couple of issues on Github against the HACS repo that talk about this problem, but they’re all either very old or locked.

I noticed that one of my custom repos, Wakatime (an addon used to track time spent using code editors) was removed from Github, and the repository is returning a 404 now.

I suspected that this was the reason that the “Custom Repositories” option was grayed out. Attempting to remove the Wakatime Repo from HACS had no effect - it was still listed even after choosing the option to remove it, and restarting after attempting to remove it had no effect.

Since this orphaned repo was graying out the “Custom Repos” option (or so i suspected), this ffectively meant that HACS was stuck in time – I was unable to add new repos, cutting me off from a lot of desired functionality in HA.

I googled around and found very little info on how to manually remove a repo from HACS, so posting some steps here in case its useful to others. This isn’t official at all, use at your own risk, editing files directly isn’t advised, etc.

Steps to remove a custom repo from HACS manually

  1. Prep
    1. Get the name or part of name of the repo you’re trying to remove (in my case, wakatime)
    2. Make sure “Terminal & SSH” add-on is enabled (this is the low-key one that doesn’t need to extra permissions).
  2. Disable HACS
    1. Turn off HACS under Integrations
    2. Restart HA
  3. Open Terminal (using the Terminal & SSH add-on)
  4. Remove the custom_component if it exists
    1. cd config
    2. cd custom_components
    3. ls to find the name of the repo
    4. If present, delete it with rm -rf wakatime
  5. cd ..
  6. Remove references to the component in hacs.repositories
    1. cd .storage
    2. vim hacs.repositories to edit HACS’ list of repos
    3. Type / and then the name of the repo to find it in the json file
    4. Delete the entry in the json file for the repo (I use dd and keep pressing dd until the section was gone, but there’s probably a vimmier way)
    5. Save and quit by typing :wq
  7. Remove references to the component in the hacs directory
    1. cd hacs
    2. grep wakatime *
    3. A file should be listed with a numeric name
    4. rm <file> where is the name of the file from the previous step
  8. Restart HACS and check to see if the “Custom Repositories” option is enabled
    1. Reenable hacs
    2. Check to see if “Custom Repositories” is available
    3. (A restart wasn’t necessary for me here)

I don’t have the patience to go through and format this markdown to text. I hope this helps someone all the same.

In the future, I wonder if HACS could be updated to move orphaned repos (those that return 404) to the already-existing blacklist. This seems like an easy way to keep people from losing functionality. Until then, this solution seems to work.


Same problem,

Removed Repo in Github, but unable to remove in HACS:

<Integration sdebruyn/homeassistant-bpost-integration> GitHub returned 404 for

Please take a moment to read OPs post. OP explains how to remove the repo from HACS. Follow his instructions.

1 Like

Tried his steps,
Removed from json, removed folder.

Only step 7 does did not get any hits.

There is also a HACS Issue on github. Following there also.


I just removed the bpost app as well and the post above worked for me.

Did you do “grep bpost *” in step 7?

Yes, only found in home-assistant.log.1

Don’t think that is important there.

Thanks for the tip.

1 Like

Yes, did it all again and seems to have worked. I guess HACS was not closed properly the first time, many thanks all!