Skip to main content

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. Learn more about devcontainers.

note

As this approach uses containers, you may face challenges exposing hardware like USB devices & adapters (onboard Bluetooth, Zigbee, ...) into the container for testing. This is possible when developing on a Linux host; however, you cannot directly access such hardware if you are using a Windows or MacOS computer for development.

Prerequisites

Getting started:

  1. Go to Home Assistant core repository and click Fork.
  2. Copy your fork's URL and paste it below, then click Open:
  3. Your browser will prompt you if you want to use Visual Studio Code to open the link, click Open Link.
  4. When Visual Studio Code asks if you want to install the Remote - SSH extension, click Install.
  5. The dev container image will then be built (this may take a few minutes), after this your development environment will be ready.
  6. You can verify that your dev container is set up properly by the following:
    1. Open the Command Palette in Visual Studio Code:
      • Mac: Shift+Command+P
      • Windows/Linux: Ctrl+Shift+P
    2. Select Tasks: Run Task -> Run Home Assistant Core
    3. A terminal should open and begin outputting activity. Check for errors and wait for the output to stop/slow down.
    4. Navigate a web browser to http://localhost:8123, and you should see the Home Assistant setup screen.

In the future, if you want to get back to your development environment: open Visual Studio Code, click on the Remote Explorer button in the sidebar, select Containers at the top of the sidebar.

Tasks​

The dev container comes with some useful tasks to help you with development. You can run these tasks by opening the Command Palette with Shift+Command+P(Mac) / Ctrl+Shift+P (Windows/Linux) and selecting Tasks: Run Task, then finally selecting 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.

Debugging with Visual Studio Code​

If the dev container was set up correctly - it supports debugging by default, out-of-the-box. It provides the necessary debug configurations, so hitting F5 should launch Home Assistant. Any breakpoints put in the code should be triggered, and the debugger should stop.

It is also possible to debug a remote Home Assistance instance (e.g., production instance) by following the procedure described here.

Manual Environment​

You only need these instructions if you do not want to use devcontainers.

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

Developing on Ubuntu / Debian​

Install the core dependencies.

sudo apt-get update
sudo apt-get install python3-pip python3-dev python3-venv autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev ffmpeg libgammu-dev

Developing on Fedora​

Install the core dependencies.

sudo dnf update
sudo dnf install python3-pip python3-devel python3-virtualenv autoconf openssl-devel libxml2-devel libxslt-devel libjpeg-turbo-devel libffi-devel systemd-devel zlib-devel pkgconf-pkg-config libavformat-free-devel libavcodec-free-devel libavdevice-free-devel libavutil-free-devel libswscale-free-devel ffmpeg-free-devel libavfilter-free-devel ffmpeg-free gcc gcc-c++ cmake

Developing on Arch / Manjaro​

Install the core dependencies.

sudo pacman -Sy base-devel python python-pip python-virtualenv autoconf libxml2 libxslt libjpeg-turbo libffi systemd zlib pkgconf ffmpeg gcc cmake

Developing on Windows​

To develop on Windows, you will need to use the Linux subsystem (WSL). Follow the WSL installation instructions and install Ubuntu from the Windows Store. Once you're able to access Linux, follow the Linux instructions.

When working in WSL make sure to keep all code/repos in the WSL environment to avoid issues with file permissions.

tip

If you 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 the dependencies:

brew install python3 autoconf ffmpeg cmake make

If you encounter build issues with cryptography when running the script/setup script below, check the cryptography documentation for installation instructions.

Setup Local Repository​

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

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

Install the requirements with a provided script named setup.

script/setup

This will create a virtual environment and install all the necessary requirements. You're now set!

Each time you start a new terminal session, you will need to activate your virtual environment:

source venv/bin/activate

After that you can run Home Assistant like this:

hass -c config

If you encounter a crash (SIGKILL) while running this command on macOS, it's probably caused by the lack of Bluetooth permissions. You can fix it by adding this permission for your Terminal app (System Preferences -> Security & Privacy -> Bluetooth).

The Home Assistant configuration is stored in the config directory at the root of your repository.