This is a community curated list of frequently asked questions (FAQ) about the installation, setup, and usage of Home Assistant. If you want to get details about a term, please check the glossary.
There will be no support for Python 2.x. Python 2 will be EOL in 2020 and it doesn’t make any sense to support a release which was planned to be retired in 2015.
New versions of Home Assistant are released on the first Wednesday of every month. The exact dates can be seen in the upcoming events calendar on the Home Assistant Developers website.
The last week of our release schedule is primarily focused on beta testing. Users who participate in the beta can view the changelog under beta release notes and get help in the
#beta channel of Home Assistant’s Discord server. Testers are also encouraged to report issues on GitHub.
When an integration does not show up, many different things can be the case. Before you try any of these steps, make sure to look at the
home-assistant.log file and see if there are any errors related to your integration you are trying to set up.
If you have incorrect entries in your configuration files you can use the CLI script to check your configuration, each installation type has its own section in the common-tasks about this:
If you try to access the configuration dialog for an entity in your Home Assistant, you might end up seeing this message:
This means that this entity does not have a unique identification, e.g., a serial number or another identifier that is guaranteed to be static and never changes. As a result, the normal editing process that allows you to change various settings through the user interface (such as the entity ID, icon, friendly name, etc.) is not possible here.
Typically, you’ll see this when you create entities manually using YAML, but it can also appear if the integration that provides this entity, cannot determine a unique ID. This however is not an error, but just a limitation of the integration you use. A few selected integrations (such as
mqtt) allow the user to define a unique ID.
- Only internally in Home Assistant.
- Entity with a unique ID: Entity ID only used as a reference, e.g., in automations or dashboards.
- Entity without a unique ID: Entity ID acts as the replacement for the non-existing unique ID plus as a reference, e.g., in automations or dashboards.
- No. It is a static identifier.
- Entity with a unique ID: Entity ID can be adjusted freely (as long as it follows the format
<domain>.<id>and does not result in duplicates in your Home Assistant). Keep in mind that if you change the entity ID, you also need to update the references, e.g., in automations and dashboards.
- Entity without a unique ID: Entity ID is considered a fixed, static identifier and cannot be changed.
In case your entity has no unique ID and therefore cannot be changed through the UI, there are some manual customization options directly through YAML files.
In case you want to read more about unique IDs, head over to this developer documentation page.
Why are you not using tools X for the documentation? Because the current solution works for us and we see no additional value in using a separate publishing platform.
Home Assistant is a FAST moving open source project. This means occasionally the official documentation will not be 100% current or complete. Since this is an open source volunteer project, we would encourage anyone who finds gaps in the documentation to click the
EDIT link at the bottom and submit any corrections/enhancements they may find useful. A step-by-step guide on how to contribute to the documentation can be found here.
In the absence of information, many users find it beneficial to look at other people’s configurations to find examples of what they want to accomplish in their own configurations. The easiest way to find these configurations is through this GitHub search.
This error indicates the image, whether for updating to Home Assistant or installing or updating an add-on, was not able to be pulled to your system. This is usually a situation where there is not enough space for the image to be downloaded. The first thing to check for is the available space on your system.
Please note, if you are running the operating system as a virtual machine; the default VM image is only about 6GB. Many VM users run into this as they have not allocated enough storage. 32GB is the minimum recommended size.
You will need to explore your own system to determine where space has gone.
df -h in the SSH add-on console to you can quickly check to see if you have space available.
If there is plenty of space available then you might check to see if you are having network issues that are preventing images from being downloaded.
No. The USB “CONFIG” stick is only used to import a network profile to
/etc/NetworkManager/system-connections/ and can be removed.
On a Home Assistant OS install, your files are on the data partition within
On the SD itself, this is an EXT4 partition labeled
On a Supervised install, they are in
Home Assistant offers a data disk feature that offloads all data to an attached USB hard drive. The SD card is still in use but is only used to serve the Home Assistant OS. Learn more about the data disk feature.
Booting from USB
Due to the complexity of USB and the USB mass storage device class, booting from a USB device is delicate. When booting from a USB drive this process has to be done multiple times (firmware/boot loader and the operating system), and there is a high chance that it doesn’t complete during one of these stages.
That said, booting Home Assistant OS completely from a USB drive (SSD or any other USB mass storage device) works with some USB devices. USB Devices that are known to work with Raspberry Pi OS (check the Raspberry Pi Forum) are more likely to work with Home Assistant OS. However, because Home Assistant OS also has U-Boot in the boot chain, there are devices which are known to work with Raspberry Pi OS but do not work with Home Assistant OS. Finding the right combination of hardware can require expirimentation.
The Raspberry Pi 4 with 8GB RAM is supported with Home Assistant OS 5.5 and later using the 32-bit and 64-bit image. The 64-bit is the better tested option at this point.
If you are looking for more information about add-ons, which won’t start or install, navigate to Configuration > Add-ons & Backups > System in the UI and check the logs.
The logs on this page are the same you would see using
su logs in the custom CLI.
Home Assistant Core is a Python program, in simple words. It can be run on various operating systems and provide the ability to track, control and automate your devices. When people talking about Home Assistant Core they usually refer to a standalone installation method.
Home Assistant is a combination of Home Assistant Core and tools which allows one to run it easily on a Raspberry Pi and other platforms without setting up an operating system first. Home Assistant is an all-in one-solution and has a management user interface that can be used from the Home Assistant frontend. This interface is not present in a Home Assistant Core setup.
Be aware that add-ons are only available in regular Home Assistant installations.
Pip should come bundled with the latest Python 3 but is omitted by some distributions. If you are unable to run
python3 -m pip --version you can install
pip by downloading the installer and running it with Python 3:
The problem which leads to
distutils.errors.DistutilsOptionError: must supply either home or prefix/exec-prefix -- not both is a known issue if you’re on a Mac using Homebrew to install Python. Please follow these instructions to resolve it.
On a Debian system, install the Python 3 YAML library by
sudo apt-get install python3-yaml.
This utility should have been installed as part of the Python 3 installation. Check if Python 3 is installed by running
python3 --version. If it is not installed, download it here.
If you are able to successfully run
python3 --version but not
pip3, install Home Assistant by running the following command instead:
python3 -m pip install homeassistant
On a Debian system, you can also install python3 by
sudo apt-get install python3 and pip3 by
sudo apt-get install python3-pip.
If you run into errors during installation, check that you’ve installed all the necessary prerequisite packages, which include
libssl-dev. On a Debian-based system, you can install these via
sudo apt-get install python3-dev libffi-dev libssl-dev
After upgrading to a new version, you may notice your browser gets stuck at the “loading data” login screen. Close the window/tab and go into your browser settings and delete all the cookies for your URL. You can then log back in and it should work.
chrome -> settings -> site settings -> storage -> search for your URL for Home Assistant-> “clear & reset”
It can happen that you get a traceback that notify you about connection issues while running Home Assistant. Eg.
ConnectionRefusedError: [Errno 111] Connection refused
The chance is very high that this is not a bug but an issue with the service/daemon itself. Check your network (DNS, DHCP, uplink, etc.) first and make sure that Home Assistant and the service are properly configured. Keep in mind that webservices can be down.
Close the windows or tab and clear the cache. The frontend is aggressively caching and clearing the cache ensures that the frontend is reloaded when you access it the next time.
Almost all integrations have external dependencies to communicate with your devices and services. Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it should show up in
The first step is trying to restart Home Assistant and see if the problem persists. If it does, look at the log to see what the error is. If you can’t figure it out, please report it so we can investigate what is going on.
This error means that you used a tab, rather than two spaces. Replace the tab with spaces.