I’d like to introduce Orphan Entity Cleaner, a custom integration for Home Assistant that helps you detect, review, and safely delete orphaned entities in your system.
What’s the problem?
When you remove an integration, unpair a device, or perform a major update, entities often remain in your registry. These “orphaned” entities:
Clutter your entity list
Degrade performance
Cause errors in logs and automations
What does Orphan Cleaner do?
This integration provides a built-in sidebar panel where you can:
Scan for orphaned entities (with extended detection logic)
Review the list with search and filter options
Select entities in bulk
Dry-run to test before deletion
Export results as JSON
Automatic backup before any deletion
Protection for entities with config_entry_id
Allowlist for critical entities (never delete)
Safety first!
I know that deleting entities can be risky, so I built in multiple safety layers:
Automatic backup creation before any destructive action
Protection for all entities with a config_entry_id
An allowlist that permanently protects critical entities like zone.home
Dry-run support to test what would happen
Admin-only access to prevent accidental actions by non-admin users
Installation
Via HACS (recommended)
Open HACS in Home Assistant.
Click on “Integrations” → three dots (⋮) → “Custom repositories”.
Add this URL: https://github.com/realsly2/Orphan-Entity-Cleaner
Select “Integration” as the category.
Click “Install” and restart Home Assistant.
Manual installation
Copy the custom_components/orphan_cleaner/ folder into your Home Assistant custom_components/ directory and restart.
How to use
Open Orphan Cleaner from the sidebar.
Click “Start Scan”.
Review the detected entities.
Use search and filters to narrow down your selection.
Select the entities you want to delete.
Export or backup the results (optional but recommended).
Run a dry-run to test.
Click “Delete Selected”.
Services & API
The integration provides several services for automation:
thank you very much for your feedback! You’re absolutely right – the integration is currently not installable via the UI. This is because it’s a Custom Integration that is not part of the official Home Assistant Core.
Here are the two ways you can install it:
1. Via HACS (recommended)
The integration is designed for HACS. You can add it as follows:
Open HACS in Home Assistant.
Click on “Integrations” → three dots (⋮) → “Custom repositories”.
Add this URL: https://github.com/realsly2/Orphan-Entity-Cleaner
Select “Integration” as the category.
Click “Install” and restart Home Assistant.
2. Manual installation (via YAML)
You asked about YAML installation – here is the step-by-step guide:
Download the custom_components/orphan_cleaner/ folder from the GitHub repository.
Copy it into your Home Assistant custom_components/ directory.
Add the following line to your configuration.yaml (this is important!):
orphan_cleaner:
4. Restart Home Assistant.
After the restart, the integration should load automatically and you will find the Orphan Cleaner panel in your sidebar.
I will update the documentation in the README.md to make the YAML step clearer. Thanks for pointing this out!
Let me know if it works now or if you have any further questions.
Update: Orphan Cleaner – New Features & Improvements
Hi everyone,
I’ve made some significant updates to the Orphan Entity Cleaner integration based on community feedback and to make it even more powerful and flexible. Here’s what’s new:
What’s new?
1. Simplified Installation
The integration now loads correctly when you add orphan_cleaner: to your configuration.yaml.
No further configuration is required – it just works!
2. Multiple Detection Methods
The integration now uses four methods to detect orphaned entities:
orphaned_timestamp – The official signal from Home Assistant (always used).
Dead config entry – If an entity’s config_entry_id points to a config entry that no longer exists.
Unavailable state – Entities that have been unavailable for a configurable period (default: 24 hours).
Heuristic (optional) – Enabled via the aggressive_heuristic flag in the service call.
3. Enhanced Services
Service
Description
orphan_cleaner.scan
Start a new scan (optional: aggressive_heuristic: true)
thank you for your comment! With the latest update, the integration still does not require any further configuration – simply adding orphan_cleaner: to your configuration.yaml is enough to load it.
What about min_orphan_age_hours and aggressive_heuristic?
These are planned as optional parameters in a future update. For now, you can use aggressive_heuristic directly in the service call:
that’s a very valid question. With the latest updates, both integrations have evolved further. Let me clarify the current relationship and differences.
Relationship to francesco.beghi’s Integration
My integration was developed independently and has a different focus. Both are now more feature-rich, but they approach the problem differently.
Key differences (as of the latest update)
Feature
My Orphan Cleaner
francesco.beghi’s Integration
Sidebar Panel
Full UI with search, filter, bulk selection
Web panel with filter and log
Configuration
Via configuration.yaml (mandatory to load) and UI
Via UI (Settings → Devices & Services → Configure)
Detection Methods
orphaned_timestamp, dead config entry, unavailable state, heuristic
orphaned_timestamp, dead config entry, unavailable state, heuristic
Service: scan
Fires event orphan_cleaner_orphans_found
Fires event orphan_cleaner_orphans_found
Service: delete_orphans
With entity_ids or all, plus dry_run
With entity_ids or all, plus dry_run
Allowlist
In services.py (customizable)
Not available
Backup
Automatic JSON backup
Not mentioned
Dry-Run
Via service or UI
Via service
UI Installation
Manual YAML or HACS
Via UI (Add Integration)
In short
Both integrations solve the same problem, but with different trade-offs:
My integration focuses on flexibility and safety – you configure it via YAML (if needed), it has a customizable allowlist, and it creates automatic backups before deletion.
francesco.beghi’s integration focuses on UI-driven configuration – you can set everything via the Home Assistant UI, which is more accessible for less technical users.
I respect francesco.beghi’s work – it’s well done and clearly addresses the same need. I believe both integrations can coexist, and users can choose based on their preference for YAML vs. UI configuration, and the specific safety features they value.
I’ve just released an update that adds two new configuration options to the Orphan Cleaner integration. You can now customize the detection behavior directly in the UI – no need to edit your configuration.yaml!
New Configuration Parameters
You can find these settings by going to: Settings → Devices & Services → Orphan Cleaner → Configure
1. min_orphan_age_hours (default: 24)
What it does: Filters out entities that are too recent. Only entities that have been unavailable for longer than this period are considered orphaned.
Why it’s useful: Prevents false positives when an integration is temporarily offline or a device is restarting.
Valid range: 1 to 720 hours (1 hour to 30 days).
2. aggressive_heuristic (default: false)
What it does: When enabled, the integration also considers entities with no config_entry_id and a platform that is not in the exclusion list (e.g., template, input_boolean, group, zone, person, etc.) as orphans.
Why it’s useful: Helps detect entities that may have been left behind by custom integrations or manual setups.
How to Update
If you installed via HACS:
Open HACS in Home Assistant.
Go to “Integrations” and find Orphan Cleaner.
Click “Redownload” (or wait for the automatic update notification).
Restart Home Assistant.
If you installed manually:
Download the latest custom_components/orphan_cleaner/ folder from the GitHub repository.
Replace your existing folder with the new one.
Restart Home Assistant.
How to Configure
Go to Settings → Devices & Services.
Find Orphan Cleaner in the list.
Click “Configure”.
Adjust the sliders and toggles as needed.
Click “Submit”.
The new settings will take effect immediately – no restart required!
Testing the New Features
You can also override these settings per service call:
So, this is the 2nd time I tried to install this Custom Integration and it’s the 2nd time I’m getting an error with no hint on how to fix it - even after a HA restart that wasn’t supposed to be required:
Why is ever entity I WOULD delete not able to be selectable? The wyze cam isn’t in use anymore but I can’t delete two associated entries and it’s shown a pending_delete_by_ha through multiple restarts. It alsi seens to consider all my broadlink integration buttons and switches created through scripts as no config or device.
What’s the problem?
What does Orphan Cleaner do?
Scan for orphaned entities (with extended detection logic)
Review the list with search and filter options
Select entities in bulk
Dry-run to test before deletion
Export results as JSON
Automatic backup before any deletion
Protection for entities with 
Installation
How to use
Services & API
Bug reports & Contributions
https://github.com/realsly2/Orphan-Entity-Cleaner/issues
Future plans
Feedback
What’s new?
How to update
Not available
