Developing Custom Integrations for Home Assistant – Getting Started

This guide shows how to get started with Home Assistant integration development. The article covers how to set up a development environment with WSL, VS Code, and devcontainers. An integration template is used to get you up and running quickly.

Development Environment

Overview

• Host: Windows machine with VS Code and remote development extensions.
  • The editor’s UI is running here.
• Linux VM: WSL2 with Ubuntu and Docker.
  • Source code is checked out here and mounted into the devcontainer.
• Home Assistant container: devcontainer optimized for component development.
  • This is where the code runs.

Notes:

• Do not install Docker Desktop on Windows. It’s not required.

Preparation

An easy way to install all the below mentioned requirements is to invoke the automation to install the Home Assistant Core devcontainer. However, it’s geared towards contributions to the HA Core repository, not towards custom integration development. It also has the downside that a lot happens behind the scenes which may be hard to understand. Finally, it creates a default WSL user devcontainers, which may or may not be to your liking.

Whether you use the automation or not, you’ll need the following:

• Windows host:
  • WSL2
  • VS Code
  • VS Code extensions:
    • Remote development extension pack (bundles the extensions Dev Containers, Remote – SSH, Remote – Tunnels, and WSL).
• WSL:
  • Ubuntu
  • Docker

I don’t cover the installation of the above in this article as there are plenty of guides for each available.

Integration Template

We’ll use ludeeus’ integration_blueprint as a template. It comes with its own devcontainer configuration and elegantly includes Home Assistant Core via its Python package, which is much more efficient than checking out the full HA repo.

Repository

Create from Template

Create a new repository in your GitHub account from the integration blueprint:

• On the integration_blueprint GitHub page, click Use this template > Create a new repository.
• Choose a repository name.
• Click Create repository.

Set Repository Properties

On the homepage of your new GitHub repository, configure its description and topics. This is required by HACS (Home Assistant Community Store).

Clone in WSL

In WSL, clone your new repository to a new local development folder in your home directory:

# Replace with your values:
# <repo-url>
# <repo-name>
git clone <repo-url> ~/code/<repo-name>

Dev Container

Open the cloned repo in VS Code on Windows via the VS Code Server for Linux. Run the following in WSL:

cd ~/code/<repo-name>
code .

The VS Code Dev Containers extension recognizes the dev container spec file .devcontainer.json and shows a prompt. Click Reopen in container.

The dev container is now being built as a Docker container in our WSL VM. This may take a few minutes. You can inspect the logs in the VS Code terminal.

Bind Mount

Once the container has been built, you’ll see your repo’s files in VS Code’s Explorer window. Any edits you make in VS Code are visible in WSL, where you cloned the repo’s files, too. This is because in the absence of specific mount instructions in .devcontainer.json, VS Code bind mounts the local Git repository root into the container.

Update Versions

In VS Code, edit requirements.txt, adjusting the HA version to the latest found here. Note the minimum required Python version on the same page and update it on the image line of .devcontainer.json, specifying the major and minor version only. For example, if your Home Assistant version requires at least Python 3.13.2, specify 3.13 in the container image setting.

Your Integration

Name Change from the Template

Set a display name and a base directory name for your integration. We’ll use the placeholders <Integration name> and <integration_dir>, respectively, in the steps below. Note that Python only allows lower-case characters and underscores (details). This is relevant for the name of <integration_dir>.

Rename the integration directory in WSL:

cd ~/code/<repo-name>
mv custom_components/integration_blueprint custom_components/<integration_dir>

In VS Code, replace the template repo name in the template’s files by pressing Ctrl + Shift + h:

• Replace https://github.com/ludeeus/integration_blueprint with <repo-url>
• Replace ludeeus/integration_blueprint with <integration_dir>
• Replace integration_blueprint with <integration_dir>
• Replace Integration blueprint with <Integration name>
• Replace ludeeus with your GitHub username in manifest.json

In VS Code, delete the contents of the file README.md as it applies to the template, not your future integration.

Rebuild the Dev Container

The replacement steps above modified the dev container spec file .devcontainer.json. Press Ctrl + Shift + p to bring up VS Code’s command palette and execute the command Dev Containers: Rebuild Container.

First Start of the Home Assistant Dev Container

In the VS Code terminal, run scripts/develop to start Home Assistant. Once that has happened, VS Code displays a prompt that HA is ready on port 8123 and can be opened in your browser. Do that and try it out.

When you’re done, close VS Code. The Docker dev container should be shut down automatically (you can verify with docker ps in WSL).

Commit Your Changes to GitHub

Git on Windows

You can easily access the WSL file system from Windows and open the repository in a Git client like Fork by using a path like the following:

\\wsl$\Ubuntu\home\<wsl-username>\code\<repo-name>

Ignoring Linux File Mode Changes on Windows

As Windows doesn’t “understand” Linux file modes (the permissions systems are too different), Git on Windows may keep showing files as uncommitted when, for example, the executable bit was set, even though everything was committed correctly. When this happens, you may not be able to convince Git that everything is fine and no uncommitted changes exist.

To work around this problem, configure Git on Windows to ignore file mode changes by setting core.filemode to false. This needs to be done just right or it won’t have any effect because the setting can be set in two places:

1. Per repository (in .git/config)
2. Globally for your user account (in ~/.gitconfig)

As the setting per repository has precedence over the global setting, we need to configure the following:

• Remove the setting from the repository (where it’s added automatically upon cloning on Linux) by deleting the line containing core.filemode from .git/config.
• Enable the setting on Linux by running git config --global core.filemode true.
• Disable the setting on Windows by running git config --global core.filemode false.

You can verify that the setting is configured correctly on Windows with PowerShell:

cd \\wsl$\Ubuntu\home\<wsl-username>\code\<repo-name>
git config --show-origin core.filemode

# Expected result:
# file:C:/Users/<username>/.gitconfig  false

On Linux:

cd ~/code/<repo-name>
git config --show-origin core.filemode

# Expected result:
# file:/home/<username>/.gitconfig     true

Git on WSL

Git Credential Manager Configuration

WSL allows for an elegant way to authenticate to GitHub by leveraging the Windows host machine’s Git Credential Manager from within WSL. Configure it by running the following in WSL (requires at least Git 2.39):

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

You also need to set your author information:

git config --global user.email "[email protected]"
git config --global user.name "Your Name"

Git Commit and Push

Navigate to the repository’s root directory ~/code/<repo-name>.

Commit and push your changes:

git add --all
git commit
git push -u origin --all