How to Create a Home Assistant Development Environment in 2026

Embarking on a journey to develop new features or components for Home Assistant begins with establishing a robust development environment. This guide will walk you through the process, ensuring you have everything you need to start coding and testing your innovations.

Whether you’re a seasoned developer or just starting out, setting up your environment correctly is crucial. We’ll explore different methods, from using visual studio Code with devcontainers to manual setups on various operating systems. Let’s get started!

Developing with Visual Studio Code and Devcontainers

The most streamlined approach to setting up your development environment involves using Visual Studio Code and devcontainers. This method provides a consistent and isolated workspace, making it easier to manage dependencies and configurations.

Prerequisites

Before you begin, ensure you have the following tools installed on your system:

• Docker Essential for running containers.
• Visual Studio Code Your primary code editor.
• Git For version control and repository management.

Getting Started

Follow these steps to set up your development environment:

1. Visit the Home Assistant Core repository and click Fork.
2. Copy your fork’s URL and paste it into Visual Studio Code.
3. Open the link in Visual Studio Code and install the Dev Containers extension if prompted.
4. Wait for the dev container image to build. This process may take a few minutes.
5. Verify your setup by opening the Command Palette and selecting Tasks: Run Task -> Run Home Assistant Core.
6. Navigate to http://localhost:8123 in your web browser to see the Home Assistant setup screen.

Troubleshooting

If you encounter issues during the setup process, follow these steps:

1. Ensure your GitHub fork is up-to-date with the main Home Assistant Core repository.
2. Clean local Docker build files by running docker buildx prune in the terminal.
3. If the build still fails, select Open configuration in recovery devcontainer and run git pull upstream dev.
4. Rebuild the container using the Command Palette.

Manual Environment Setup

If you prefer a more traditional development environment, you can set it up manually. This method requires installing dependencies specific to your operating system.

Ubuntu / Debian

For Ubuntu or Debian systems, install the core dependencies using the following commands:

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 build-essential

Fedora

On Fedora, use these commands to install the necessary 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

Arch / Manjaro

For Arch or Manjaro systems, install the dependencies with:

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

NixOS

On NixOS, create a default.nix file with the following content and activate it using direnv

let
pkgs = import  { };
in
pkgs.mkShell {
packages = with pkgs; [
 autoconf
 clang
 cmake
 ffmpeg
 ffmpeg.dev
 gammu
 libffi.dev
 libjpeg.dev
 libxml2.dev
 libxslt.dev
 openssl_3.dev
 pkg-config
 python314
 zlib.dev
];

env = {
 LD_LIBRARY_PATH = "${pkgs.libjpeg.out}/lib";
};
}

Windows

To develop on Windows, you’ll 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, ensure all code and repositories are stored within the WSL environment to avoid file permission issues. If you encounter difficulties accessing the development instance via http://localhost:8123 use the inet address of the eth0 adapter instead.

MacOS

On macOS, install Homebrew and use it to install the dependencies:

brew install python3 autoconf ffmpeg cmake make

Some Python dependencies of Home Assistant, such as cryptography and orjson contain extensions written in Rust. If no prebuilt wheel is available for your Python version and platform, pip builds them from source, which requires a Rust toolchain. If the script/setup script fails because rustc or cargo is missing, install Rust as well.

Setup Local Repository

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

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

Install the requirements with the provided script named 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, activate your virtual environment using:

source.venv/bin/activate

After activating the virtual environment, you can run Home Assistant with the provided command. 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 in System Preferences.