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.


Python 2

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 every three weeks on a Wednesday. The exact dates can be seen in the upcoming events calendar on the Home Assistant Developers website.

The third 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.


My integration does not show up

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 check_config script to assist in identifying them: hass --script check_config.

This entity does not have a unique ID?

When you see

This entity does not have a unique ID, therefore its settings cannot be managed from the UI

this simply means that you can’t change the entity_id or the friendly name from the UI. You can still use the Customizations menu to customize that entity. Typically you’ll see this when you create entities using YAML.

Why are you using YAML for the configuration file?

And not JSON or XML for the configuration file? Because YAML can be written by hand, you don’t have to care about commas or tag and it’s a superset of JSON.


Documentation tools

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.

Missing Documentation

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 this page on Github link in the top right 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.


Home Assistant vs. Home Assistant Core

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.

No module named pip

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:

python3 get-pip.py


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.

libyaml is not found or a compiler error

On a Debian system, install the Python 3 YAML library by sudo apt-get install python3-yaml.

pip3: command not found

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 python3-dev, libffi-dev, and libssl-dev. On a Debian-based system, you can install these via apt-get:

sudo apt-get install python3-dev libffi-dev libssl-dev


After upgrading, your browser login gets stuck

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.

Android Chrome:

chrome -> settings -> site settings -> storage -> search for your URL for Home Assistant-> “clear & reset”

Connection error

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.


The dependencies which are used by Home Assistant are stored in the folder deps of the configuration folder directory. After an upgrade the dependencies will be upgraded as well.

Frontend is acting weird

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.

Problems with dependencies

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 home-assistant.log.

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.

found character ’ ’ that cannot start any token

This error means that you used a tab, rather than two spaces. Replace the tab with spaces.