Drop support for the Home Assistant Core installation method

[frenck]

Context

Home Assistant currently has 4 supported installation types:

• Home Assistant OS
  This installation method is popular and provides the whole package. It is what we ship on our Home Assistant hardware, but it is also mostly used on a Raspberry Pi or by running a VM.
• Home Assistant Container
  This is the second most popular installation method and is mostly used to run Home Assistant on Docker. We use these same containers to run on the Home Assistant OS installation method.
• Home Assistant Supervised
  Basically, Home Assistant OS, but… with your own OS. So, it runs the full stack, except the operating system part, which the user brings and maintains.
• Home Assistant Core
  The old-school installation methods, in which a user installs Home Assistant directly into a Python virtual environment.

The focus for this proposal (as the title already gave away) is the last one: Home Assistant Core.

Background

The core application of Home Assistant itself is a Python application (which is where the installation methods got its name from), and the installation method is basically how we also develop Home Assistant. We install and run the Python application directly.

The big difference between running it for production use and development is that for production use, you’d probably install the Home Assistant Python package we publish on PyPI, while for development use, you’d run an editable install from the source code directly from GitHub.

At the time of writing this proposal (11 February 2025), the Core installation method is the least popular, with just 2,57% of installations. Since this method is complex and rarely used, maintaining official support is not justifiable.

Ref: https://analytics.home-assistant.io/

Proposal

The proposal is to drop Home Assistant Core as an officially supported installation method. This means:

• It will no longer be documented as an installation method for end users.
• It will no longer receive official support.
• Users will be encouraged to migrate to Home Assistant OS or Home Assistant Container.

What this means in practice

• This does not remove the ability to run Home Assistant this way.
• It will remain documented only in developer documentation for contributors who need it for development purposes.
• However, the Home Assistant project will no longer actively support pure Python core installations.
• It will no longer be an officially recommended installation method for production use.

Reasoning

There are several strong reasons to drop this method as an officially supported installation:

1. Complexity & user experience

• Home Assistant Core is the second most complex installation method (Supervised being the most complex).
• The installation steps are not beginner-friendly and often require Python knowledge.
• Users frequently attempt to set it up on WSL or various Linux distributions, leading to issues due to differences in dependencies and configurations.

2. (End-user) Maintenance burden

• This method often leads to documentation changes and user support issues due to distro-specific variations.
• Python versions vary by distribution, and some users get stuck when we move to a newer version.
• Managing dependencies is increasingly complex. Recent examples include:
  • Transitioning to uv for Python package management.
  • The new go2rtc dependency.
• In all other installation methods, we manage these aspects for the user.

3. Low adoption rate

• With only 2.57% of installations, the impact of dropping this method is minimal.
• Compared to Home Assistant OS (77.13%) and Container (17.00%), Core is used by a small fraction of the user base.
• Developers who prefer this method already have the skills to run Home Assistant without official support.
• Given its high complexity and low adoption, maintaining official support is no longer justified.

4. Negative perception & support overhead

• The complexity of this installation method is poorly reflected in Home Assistant as a whole. Users struggling with this method sometimes perceive Home Assistant itself as difficult.
• Users who initially succeed often encounter issues later—particularly with service scripts, dependency updates, or Python version mismatches.
• Supporting a method with such variability and edge cases diverts resources from more widely used installation methods.

5. Better alternatives exist

Most Home Assistant Core users have better alternatives:

• Users who want a full Home Assistant experience with minimal maintenance should migrate to Home Assistant OS.
• Users who want more flexibility and control should switch to Home Assistant Container.

Consequences

The consequence is that we will remove advanced installation methods as a possibility from our end-user documentation and no longer advertise or recommend using them to run Home Assistant on a production instance.

1. Deprecation

   • A 6-month deprecation period will be applied.
   • A repair issue will be raised on all active Home Assistant instances using this installation method, advising users to migrate to a different installation.
   • All integrations exclusively available for this installation method, will be deprecated at the same time.

2. Architecture Decision Record (ADR) adjustments

   • Mark ADR-0016 (Home Assistant Core) as Reverted.
   • Update ADR-0012 to remove Home Assistant Core from the list of supported installation methods.

3. Documentation cleanup

   • Remove Core from all end-user documentation.
   • Ensure that developer documentation still covers how to set up a development environment.

4. Community announcement

   • Publish a blog post to inform the community about this decision and provide guidance on migration options.

5. Mark as unsupported in Home Assistant

   • After the deprecation period ends, the repair issue will be removed, and Home Assistant will formally consider this method unsupported.

6. Clean up deprecated integrations

   • After the deprecation period ends, all integrations that exclusively worked in this installation method and have been deprecated before, will be removed.

[parautenbach]

I can appreciate the challenge of supporting so many platforms: I've been involved in commercial products that are multi-platform.

As an alternative to deprecating this installation method, how about constraining it to Debian, like for Supervised?

I would like to understand the overhead of maintaining the HA Core installation method technically. I get the points around less confusing documentation (like whether add-ons are supported) and improving perceptions. That said, I basically never see anybody being pushed towards HA Core, so I'm not sure how HA is perceived as complex from that point of view. If it's about users' difficulty to choose an installation method, then perhaps, but otherwise most of the "HA is complex" complaints I see aren't related to the installation method (it's more about understanding certain concepts – like triggers vs. conditions – used in HA, and, famously, the use of templating).

Regarding technical overhead, the team already needs to maintain packges (e.g. pinning version and tracking changes) as a best practice. I don't see this changing, since this is the foundation for all the other installation methods.

Could you also state the 2.57% adoption rate of HA Core as the absolute number of users? This will give a fuller picture on the actual impact of this change.

While it may be argued that HA Core is complex, it needs to be said that it is the most flexible method, as there are no additional layers to break through. What has prevented me so far from switching to HA Docker as the closest alternative to HA Core, is the use of the discouraged --privileged mode. Remember, this is stated as the default for running HA Docker, not as an exception as and when needed. I don't run the hass process as root, so neither should I need to run HA Docker with --privileged. This is a crude approach. Access to peripherals on the host system is of course possible via the --device option which can be controlled more granularly. I know there are cases that cannot be covered that way, but I don't know if that's applicable to HA.

[frenck]

Please note: We won't stop you from using or running it. This is about official support, documentation and recommendation. If you want to Home Assistant using X, do it. There are many more installation methods out there, used by the community, that we don't support today.

[parautenbach]

We won't stop you from using or running it.

I got that the first time around. :-) My appeal is to better understand where the sticking points are currently for supporting it, and a request not to drop it. I've made more points, so I'll wait patiently for those to hopefully be answered too in due time.

There are many more installation methods out there, used by the community, that we don't support today.

True, but HA Core is extremely close to the dev workflow.

[frenck]

True, but HA Core is extremely close to the dev workflow.

That will remain as, as is written in the proposal. This proposal is not about developing for Home Assistant.

[parautenbach]

I think we're missing each other: What is the technical overhead of maintaining the HA Core installation method when it is extremely close to the development workflow? I'm coming from the perspective that technically you have everything in place to allow the HA Core installation method to be supported, due to the fact that there's large overlap with the development workflow. My argument is about overheads.

I would not like to labour this point. I hope it's clearer now.

I've made several other points that I hope will be addressed too.

[frenck]

What is the technical overhead of maintaining the HA Core installation method when it is extremely close to the development workflow

This proposal isn't about the technical overhead. This proposal is about end-user recommendation, documentation and support.

[joostlek]

So there are a couple of integration that depend on core (or SSHing into your container to install extra dependencies). Say a gstreamer and a tensorflow. Would these also be deprecated and removed since they will become very hard to use in any of the supported systems?

[frenck]

Good point, I'll adjust the proposal to include handling for those (as they would become deadbeef afterwards). 👍

[allenporter]

Notably, Analytics shows both of these have 0 installs -- unless there's a bug in the reporting, it seems like these may already be deadbeef in practice

[CoMPaTech]

Semi-note that analytics only represent opt-in AFAIR so they are indicative but not conclusive?

[bdraco]

This one is a bit of a conflict as I run a core install for myself.

While we don't track install types by issues, and my experience is bound to be anecdotal, from the perspective of working the issue queue, core installs generate an outsized number of issue reports and development work to support because there are so many potential configurations. I estimate that 15% of the time I devote to Home Assistant development goes to supporting corner cases in core installs, which doesn't include all the time spent downstream in libraries to handle these corner cases. It's a significant time sink. Dropping support won't get all the time back as downstream libs I contribute to (like zeroconf and aiohttp) are also used outside of HA and will still need to support many of these cases.

Since we have it as a supported method, I've felt that time should be devoted to supporting it; however, that comes at the price of building new things, and I can count the number of months that I've had to defer new features in favor of spending time chasing core corner cases. While I like solving these types of problems, and thats why I do it, it's to the detriment of everything else that could be done.

It comes down to a few things that push towards supporting this proposal:

• Core installs have a terrible user experience and are awful from a support experience. Most users who open an issue with a core install are likely to walk away frustrated because a tiny pool of people can solve their problem, and there isn't the bandwidth to solve most of the issues.
• It's difficult for me to keep my core install running as there is no guarantee it will even build, let alone work.
• We have no formal or automated testing of core installs.
• It's taking time away from solving issues that more users care about.

[prairiesnpr]

I'm torn on this, I get that core increases the support burden and as someone who uses the core install method, I'm biased towards it. But given that, I still hate to see it go away. I'm always tweaking core components, either for testing or because of that pesky ADR that won't allow us to update any integration that doesn't have a UI config flow. If core goes away, that all gets much more difficult. I also suspect that core users are probably the least likely to opt into metrics, but who knows on that.

Anyways, I get that this proposal will go through, I just wanted to post a lament for the loss of the core install.

[mib1185]

From the proposal description:

What this means in practice

This does not remove the ability to run Home Assistant this way.

It will not go, it will just not be recommended to be used that way, nor mentioned in the end-user documentation anymore

[parautenbach]

It will not go, it will just not be recommended to be used that way, nor mentioned in the end-user documentation anymore

If there's potentially no Pypi package, installation would mean pulling from GitHub directly. See frenck's reply.

[balloob]

Python package management supports installing a Python package from a release zip hosted on GitHub. So that shouldn't be a problem.

[parautenbach]

Good point, I forgot about that option.

[frenck]

Something I realized just now, if we consider this proposal to be accepted, would it mean we would stop distributing Home Assistant on pypi?

[allenporter]

Something I realized just now, if we consider this proposal to be accepted, would it mean we would stop distributing Home Assistant on pypi?

Not supportive. I think in repeating what was said above me ,(sorry missed that)

There are ways to develop using home assistant outside of cloning the GitHub repo. My development approach for custom components, including CI, relies on home assistant as a library. This includes the pytest custom component package for automated testing.

That said, most of this is done in a dev container so there may be alternative ways to improve this workflow.

My intuition is that pypi distribution is quite useful in other non obvious ways.

Can you better articulate which goals this advances in the proposal? I think most users don't discover how to install core via pypi and just updating the documentation is enough.

[parautenbach]

The PyPI upload doesn't cost us much in terms of maintenance load as the workflow is already setup.

My intuition is that pypi distribution is quite useful in other non obvious ways.

The above is what I was after with the question in my own post:

What is the technical overhead of maintaining the HA Core installation method when it is extremely close to the development workflow?

My development approach for custom components, including CI, relies on home assistant as a library.

Ditto.

[balloob]

I think that we should keep the PyPI upload, but mark the README that this is not meant for running Home Assistant. We could consider also adding some code for PyPI in hass that prints this while running HA. Maybe requiring an extra flag to run hass ?

I initially was leaning to letting people install HA using Python packaging pointing at GitHub. However, I realized that we do things like downloading and bundling translations. Those are not currently captured in our tagged releases.

[CoMPaTech]

I'd suggest not (over)complicating the normal ingestion with things as requiring a flag to run it. If one tends to use a method outside of the documented path, it would be up to them to handle the consequences. Continuing the PyPi upload sounds like a great plan, just documenting a oneliner/warning on it's description that it's not for end-user consumption should be good enough?

[balloob]

I think that we should add a warning during onboarding and in the config page of Home Assistant they are running a development version that is not meant for production.

[balloob]

I support this proposal.

[kbahey]

Let me preface this by saying I have been using Home Assistant since February 2018 (at least, maybe the year prior as well). My installation has grown in scope over the years, and runs well.

My setup is Ubuntu Server 22.04 LTS on a Raspberry Pi 4, and HA is in a venv.

There are several reasons I don't want to use containers nor Home Assistant O.S.
These reasons include:

0. The server runs well, and does what I want
1. It has excellent maintainability and long term release via the apt repositories
2. There are no extra levels of abstractions or blobs
3. There are other applications on it (e.g. rtl_433, Mosquitto, MySQL, InfluxDB, Grafana, a few custom things)
4. There are crucial custom shell scripts that get called from automations

My plan is to use Astral's uv to upgrade the Python version, then Core, then Ubuntu to 24.04 LTS. Astral's uv solves the Python version issue that holds Core behind.

I don't mind the Core install method being removed from the documentation for end users, as long as it is documented in the developer's documentation, and is not dropped as a method for running HA.

If there is no PyPI package, but uv can still install and upgrade HA from zip files (or wherever), then that part is not an issue.

So keep this option for technical folk who can handle it, like myself.

[carstenfuchs]

I can only second this.

I've started with Home Assistant only last year, but otherwise my setup is similar to that of @kbahey 's. The Core install gives us a simple and clean method that is lightweight and unobtrusive on systems. It also allows for easy access via SSH e. g. for editing YAML files or accessing backups.

I too switched to uv for upgrading, which nicely decouples the Python version from the Python supported by the OS and thus much simplifies the installation and upgrading of Home Assistant (see e. g. my post here). Maybe that alone would render many support questions on Core obsolete? It would be even easier if the install was placed into a directory of the local, non-root user.

• So maybe quite the opposite of this issue would be an option: Improve the Core install method both by documentation and implementation so that it is more robust and more viable to the average user?
• Just a guess: I too use Ubuntu, but someone who has an RPi already in use for other purposes might benefit from a Core install more than from the other methods.
• And honestly I doubt that the statistics of 2.57 % are reliable: Especially for Core installs I can see several reasons (privacy concerns; deliberate local network restrictions; red flagged, discouraged installation method) that cause significantly lower numbers than the other installation methods. I also dare claim that people who use the Core install have a slightly different approach to Home Assistant (or building automation in general) than people who use methods that are easier, but more isolated from the rest of the OS.

I'm aware that my arguments can probably not chance the outcome of this issue. If the Core install method was left in the developer's docs would be okay for me. But what really bothers me:

Home Assistant will formally consider this method unsupported.

Does that mean that even though documented in the developer's docs, if I happen to have a question about it at some time in the future, I will be told something like: "You know what you did, not supported, go fix it on your own." ?

[frenck]

if I happen to have a question about it at some time in the future, I will be told something like

If this is specific bug report: Yes. On the community: 🤷 Anyone can decide themselves who they want to help or not.

[frenck]

So keep this option for technical folk who can handle it, like myself.

Yes, you actually reworded the proposal.

[skandalfo]

I run a small server with a bunch of home services. One of them is my HA Core installation. Both HA and Octoprint are handled via systemd services wrapping the relevant unprivileged user and venv setup. Caddy easily provides an HTTPS virtual host based frontend for these two and a couple more that I can easily access from outside of my home network.

I've had a couple of "situations" during my time running HA Core due to OS, Python or dependency upgrades, but nothing that ever took more than one hour to fix just by searching the web a little bit.

So far I didn't feel inclined to move anything to a container based setup, or to deploy functionality (voice recognition?) which was only available as containers. Python virtual envs have been enough to isolate the dependency issues, and my server seems to run with very low overhead.

I run a couple of automations that require scripts to access system-wide installed binaries, like Android's adb tool to restart/reload/upgrade in-wall "liberated" NSPanel Pro tablets. In the past I ran custom monitoring scripts that would require sudoers setup to work. I'm guessing this kind of thing would become more complicated for me if I had to set them up for access from containers.

I don't really have a good reason myself to move to containers. For me they conflate packaging isolation (useful for me to some extent) with runtime isolation (not so useful if this forces me to run an overlay networking setup I don't want or if it limits the custom setups I sometimes need to do).

I'm not developing HA. You could say I develop custom automations, but I run my "production HA" with the Core installation method and I'm happy with it.

I'm perfectly ok with devs cutting on the time they spend supporting this kind of installation, but I'm a bit wary of the capability for running a "production Core setup" being pushed to the "community fringe". My worry is about the other sense of the relationship: will it be still possible to contribute fixes to mainstream HA if it happens to break in non-dev-mode Core setups? Or will these fixes be rejected and redirected to some kind of community fork or overlay that will be always chasing a moving target?

IOW, I'd prefer the installation method to remain officially acknowledged in docs and the main codebase, even if it's at a "low/best-effort" support level, or if its maintenance is delegated from the main devs to the subset of people interested in keeping this kind of setup working going forward.

[kbrown01]

I have no issues but would respectfully request instructions on the best way to move.
I have one (my original and the production system for house and winery) which is Core. Already upgraded Python and SQLite.
I have HA Green in a separate install (at my gate, a mile from the house/winery so on it's own network).
I have a Proxmox install of HassOS which I use for development most of UI.

If I have clear, concise directions to create a new HassOS and move all things Core over that is great.
But I suspect somethings are missed.
Like it took a lot of work to stream audio, not sure I can replicate that. Several devices are USB/Serial and I have one. Switching it between machines, testing and moving it back and forth seems troublesome.

Just because, I restored a backup from core to DEV. It worked but only from a high level. Now i have start flipping devices, restoring media streaming, relinking 6 Televisions, and I assume many more things that will likely take a week or more

Work I assume I have to do.

[gwww]

Does this proposal affect developers? Specifically the workflow of cloning core, running script/setup, and then running hass. I read that the proposal will not affect running this way, just want to make sure that the workflow I describe still works.

[pantherale0]

I would say it doesn't - I read this proposal (and similar ones) as something that will mainly impact end users. For those of us developing around HA, running HA core via the cli will continue to work, but for a production deployment as an example, running like this won't be supported by the core HA team.

End users should migrate away to a supported option if they want to continue receiving support.

[jeeftor]

Seems fine to me - as long as I can run hass -c config to develop all is good

[carstenfuchs]

• However, the Home Assistant project will no longer actively support pure Python core installations.

Can you please explain what this means? What is the definition of active support?

[mib1185]

the same question (reworded) has been asked in #1197 (reply in thread) and answered in #1197 (reply in thread)

TL;DR: the core installation method will be supported by the community (eq. community Forum or Discord chat server)

[CoMPaTech]

That the core team / project won't spend time on it until it affects the project as a whole? But that the community can provide for / cater / tinker / etc. whatever they want with it. I'd read it more as 'average users shouldn't be using this, so Core Team / Project / Open Home / Nabu Casa (whichever may apply) won't spend any meaningful time maintaining it in any way or form that benefits the (average?) end user.

[balloob]

After collecting community feedback and thoroughly weighing the long-term maintenance benefits against the impact on affected users, the core team has approved this proposal.

The aim is that starting with Home Assistant 2025.6, we will begin a six-month deprecation period.

We understand this change may be disruptive for some, and it was not taken lightly. However, this step is necessary to ensure Home Assistant can continue to evolve and remain maintainable for the future.

Thank you to everyone who participated in the discussion. Your input was essential in guiding this decision.

[MickLesk]

Hi @balloob, @frenck,

we were honestly a bit surprised by the decision to deprecate the Home Assistant Core installation method. While we understand the reasoning and maintenance burden behind it, one concern remains from our side:

There’s currently no official migration path from a Core installation to Home Assistant OS. We've had several users on our community scripts repo ask about this over the past months, and there’s still no documented way to perform such a migration cleanly – especially for setups with custom automations, system-wide integrations, or local services tightly coupled to the Core environment.

Is there any plan to provide such a migration tool or guide before the deprecation period ends? Even a "best-effort" conversion guide would help users who are otherwise left in a dead end.

For reference:
From our metrics collected over the last 90-120 days, the current install base looks like this:

• Home Assistant OS: ~9500 instances
• Home Assistant (Docker): ~5400 instances
• Home Assistant Core: ~2500 instances

So while Core is clearly the least used, it’s still a non-negligible share – and for many of these users, switching to OS is not a trivial change due to constraints or use cases (e.g., running on shared Linux hosts).

Thanks for your great work overall – and for considering this point!

Best regards,
MickLesk & community-scripts maintainers

---

Reference:
community-scripts/ProxmoxVE#4487 (comment)
community-scripts/ProxmoxVE#4489

[frenck]

There’s currently no official migration path from a Core installation to Home Assistant OS.

There is. Backup & restore can be used across all currently official installation methods we offer.
See also the post here: https://community.home-assistant.io/t/feedback-requested-deprecating-core-supervised-i386-armhf-armv7/880968

[MickLesk]

Ah great, that's relatively new, isn't it? I've been using the OS exclusively for over 3 years, I've only ever see it in our repo that it didn't work from Core/Docker.

[frenck]

Yes: https://www.home-assistant.io/blog/2025/01/03/release-20251/#overhaul-of-the-backup-system

[MickLesk]

Perfect, thanks, i write an information tomorrow for all "Core" Users and link this hard into the Script