Set up Development Environment

You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up.

Developing with Visual Studio Code + devcontainer

The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories.

Prerequisites

More info about requirements and devcontainer in general

Getting started:

  1. Fork the repository.
  2. Clone the repository to your computer.
  3. Open the repository using Visual Studio code.

When you open this repository with Visual Studio code you are asked to "Reopen in Container", this will start the build of the container.

If you don't see this notification, open the command palette and select Remote-Containers: Reopen Folder in Container.

Tasks

The devcontainter comes with some useful tasks to help you with development, you can start these tasks by opening the command palette and select Tasks: Run Task then select the task you want to run.

When a task is currently running (like Preview for the docs), it can be restarted by opening the command palette and selecting Tasks: Restart Running Task, then select the task you want to restart.

Preparing Your environment

It is also possible to set up a more traditional development environment. See the section for your operating system. Make sure your Python version is 3.7 or later.

Developing on Linux

Install the core dependencies.

$ sudo apt-get install python3-pip python3-dev python3-venv

In order to run script/setup below you will need some more dependencies.

$ sudo apt-get install autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev pkg-config
$ sudo apt-get install -y libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev libavfilter-dev
tip

Different distributions have different package installation mechanisms and sometimes packages names as well. For example CentOS would use: sudo yum install epel-release && sudo yum install python36 python36-devel mysql-devel gcc

Additional dependencies exist if you plan to perform Frontend Development, please read the Frontend section to learn more.

Developing on Windows

Since Home Assistant is mainly designed and developed on Linux distributions, on Windows 10 you can setup a Linux subsystem.

Open Powershell as an Administrator and run

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

From Windows Store install Ubuntu.

For those already running Ubuntu 18.04 on WSL

If you are running Ubuntu 18.04 on Windows Subsystem for Linux some additional steps are needed to install the latest FFmpeg version.

$ sudo add-apt-repository ppa:savoury1/ffmpeg4
$ sudo add-apt-repository ppa:savoury1/graphics
$ sudo add-apt-repository ppa:savoury1/multimedia
$ sudo apt-get update
$ sudo apt-get install ffmpeg

When the Linux subsystem is set up, perform install as for Linux.

$ sudo apt-get update
$ sudo apt-get install python3-pip python3-dev python3-venv python-wheel-common
$ sudo apt-get install autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev
$ sudo apt-get install -y libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libavresample-dev libavfilter-dev

Hint: Git is included in Linux subsytem.

When invoking your installation (see below), make sure to specify a folder for configuration which is accessible from Windows.

$ mkdir -p ../config
$ hass -c ../config
tip

You may find that you cannot open the development instance via http://localhost:8123 when using WSL. Instead, within a WSL terminal, find the inet address of the eth0 adaptor by running ip addr show eth0. Then use this address, excluding the CIDR block, to access the development instance, i.e. if your inet is listed as 172.20.37.6/20, use http://172.20.37.6:8123.

Developing on macOS

Install Homebrew, then use that to install Python 3:

$ brew install python3 autoconf

Then install ffmpeg:

$ brew install ffmpeg

Setup Local Repository

Visit the Home Assistant Core repository and click Fork. Once forked, setup your local copy of the source using the commands:

Windows users should be sure to clone to a path that inside the WSL (ex: ~/).

$ git clone https://github.com/YOUR_GIT_USERNAME/core.git
$ cd core
$ git remote add upstream https://github.com/home-assistant/core.git

Note that core.git should be replaced by the name of your fork (default being core.git). If unsure check your GitHub repository.

Setting Up Virtual Environment

To isolate your environment from the rest of the system, set up a venv. Within the core directory, create and activate your virtual environment.

$ python3.7 -m venv venv
$ source venv/bin/activate

Install the requirements with a provided script named setup.

$ script/setup

Invoke your installation, adjusting the configuration if required.

$ hass

Logging

By default logging in Home Assistant is tuned for operating in production (set to INFO by default, with some modules set to even less verbose logging levels).

You can use the logger component to adjust logging to DEBUG to see even more details about what is going on:

logger:
default: info
logs:
homeassistant.core: debug
nest.nest: debug
asyncio: debug
homeassistant.components.cloud.iot: debug
Last updated on