Building a Home Assistant Custom Component Part 5: Debugging

4 minute read

This is the fifth and final part of a multi-part tutorial to create a Home Assistant custom component.


This is the final part of the tutorial for creating a Home Assistant custom component. This post will cover how to debug your custom component to ensure it works as expected and to figure out why some thing might not be working like you expect.

I must admit, I only recently learned about the devcontainer offered by Home Assistant for local development. Prior to learning about it, I would modify files locally, scp them to the the correct folder on my Home Assistant instance then restart my instance. Not only was this slow, but it also meant my Home Assistant instance powering my house would have to go down constantly as I tried out changes when debugging a problem. As it turns out, Home Assistant had already developed a solution for local development that doesn’t require taking down your “production” instance. Enter the devcontainer.

Visual Studio Code + devcontainer

To utilize the devcontainer, you will first need to install Visual Studio Code. Visual Studio Code is a free IDE that is extremely popular and has plenty of extensions for speeding up and improving development. After installing there are a few other requirements that must be installed, check out the official documentation for more details.

After you have installed the prerequisites and cloned the home-assistant/core repository, you can start Visual Studio Code and open the cloned directory. When opening the folder for the first time, Visual Studio Code will detect the devcontainer and ask if you would like to open the editor in the container, select yes. This first open will build the container which may take a minute or two. Subsequent opens will be much quicker as it will reuse the built container.

Configuring the devcontainer

Before we proceed further we will need to copy our custom component into the config directory in the root of the cloned home-assistant/core repository. Note that you may need to elevate your permissions as docker will create files owned by root in the config directory. Alternatively you can use the built-in terminal in the IDE which gives you a root prompt with the correct permissions.

First navigate to /path/to/cloned/home-assistant/config and create a custom_components directory. From there copy your custom component directly into this new folder. For our tutourial project we’d copy the entire github_custom directory.

Next add any necessary configuration to the configuration.yaml file. Since our tutorial custom component uses the config flow, we don’t need to add anything as we can add the integration and set it up in the configuration UI.

Run Home Assistant

Now that we have our files copied and configuration updated, return to Visual Studio Code and click on the Run tab (Ctrl+Shift+D) in the left panel. You will see a mostly empty panel with a dropdown at the top that contains debug configurations that can be run. At the time of writing there are 2 options, Home Assistant which runs a local instance and Preview (nodejs) which runs a local instance of the documentation site.

VSCode Run Panel
Visual Studio Code Run panel.

Select Home Assistant from the dropdown and click the green triangle to start the debugger. This will also open the Terminal panel at the bottom where you can see the Home Assistant logs. You can now navigate to http://localhost:8123 in your browser and you will be guided through the initial setup of Home Assistant (creating your user, etc.). In Visual Studio Code you will also see a debug toolbar pop up near the top center of the IDE.

VSCode Debug Toolbar
Visual Studio Code debug toolbar.

The debug toolbar contains controls for the following operations in the order the icons appear to the right:

  • Pause/Resume
  • Step over
  • Step into
  • Step Out
  • Restart
  • Stop

Check out the Visual Studio Code documentation for more details on what each operation does. The most used buttons will be to resume the program after hitting a breakpoint and restarting Home Assistant after making python code changes.


Breakpoints are extremely useful for being able to stop program execution and inspect variables at a particular spot in your code. To set a breakpoint find the line where you want to pause the program flow and inspect the variables and click to the left of the line number. This will add a red dot which indicates a break point. When you hit that code while navigating Home Assistant in your browser, it will automatically pause the program and allow you to inspect values in the run panel.


In the screenshot above you can see the local and global variables along with their values. After you are done inspecting the values you can click the resume button in the debug toolbar to continue program execution until it hits another breakpoint.

Wrap Up

As you can see the devcontainer inside Visual Studio Code makes debugging your custom component much simpler and faster.

I sincererly hope that these posts have helped you understand how you can develop your own custom component (and possibly even add it to Home Assistant at some point in the future). Many of the concepts documented in these posts also apply to the official Home Assistant code base, so I highly encourage you to contribute or become a code owner of an existing integration.