This guide provides instructions for installing Homebridge on Windows 10/11 using Microsoft Hyper-V virtual machines.

We recommend using the Homebridge VM Image for the best experience on Windows with Hyper-V. This provides:

• Pre-configured Debian-based virtual machine
• Automatic updates for Homebridge, Node.js, and plugins
• Better performance and stability
• Simplified setup process
• Regular security updates

View Homebridge VM Image Installation Instructions →

The instructions below describe the legacy Docker-based installation method using a Boot2Docker ISO. This method is still functional but is no longer actively maintained.

Note: New users should prefer the Homebridge VM Image method above.

• Homebridge on Windows using Hyper-V
  • Recommended Installation Method
  • Legacy Installation Method (Docker-based)
    • Table of Contents
    • Prerequisites
    • Enable the Hyper-V Role
    • Create External Virtual Switch
    • Create Homebridge Virtual Machine
      • homebridge-vm-image.iso (70 MB)
    • Manage Homebridge
    • Hyper-V Manager
    • How To Uninstall Homebridge
    • Major Node.js Version Updates
    • Configuration Reference
  • Need Help?

Before you get started, make sure you have the following:

• A computer running an up-to-date version of Windows 10/11 Enterprise, Pro, or Education (64-bit)
• ⚠️ Windows 10/11 Home Edition is NOT supported - it cannot run Hyper-V
• VT-x / AMD-V capability enabled in your system BIOS
• An account with Administrator privileges
• A DHCP-enabled network

1. Right-click on the Windows button and select Apps and Features
2. Select Programs and Features on the right under related settings
3. Select Turn Windows Features on or off
4. Select Hyper-V and click OK

When the installation has completed, you will be prompted to restart your computer.

You need to create a virtual switch that allows the Homebridge virtual machine to connect to your local network.

1. Open Hyper-V Manager (press the Windows key and type "Hyper-V Manager")
2. Select the server in the left pane, or click Connect to Server... in the right pane, then select Local Computer and click OK
3. In Hyper-V Manager, select Virtual Switch Manager... from the Actions menu on the right
4. Under the Virtual Switches section, select New virtual network switch
5. Under "What type of virtual switch do you want to create?", select External
6. Select the Create Virtual Switch button
7. Under Virtual Switch Properties, give the new switch a name such as External VM Switch
8. Under Connection Type, ensure that External Network is selected and Allow management operating system to share this network adapter is checked
9. Select the physical network card to be paired with the new virtual switch (your ethernet or WiFi adapter)

1. Select Apply to create the virtual switch. You will likely see a warning message. Click Yes to continue.

1. Select OK to close the Virtual Switch Manager window

Download the legacy Homebridge VM ISO file:

Follow these steps to create your virtual machine:

1. In Hyper-V Manager, select New then Virtual Machine... from the Actions menu on the right
2. On the Before You Begin tab, click Next
3. On the Specify Name and Location tab, give your virtual machine a name, such as Homebridge
4. On the Specify Generation tab, choose Generation 1
5. On the Assign Memory tab, allocate at least 1024MB of RAM, and UNCHECK the "Use Dynamic Memory" checkbox
6. On the Configure Networking tab, set the Connection to External VM Switch (created in the previous step)
7. On the Connect Virtual Hard Disk tab, set the hard disk size to 16GB or larger
8. On the Installation Options tab, select "Install an operating system from a bootable CD/DVD-ROM", then select "Image File" and choose the homebridge-vm-image.iso file you downloaded
9. On the Summary tab, click Finish

Once created, double-click on the virtual machine in Hyper-V Manager, then click Start.

The VM will boot and start Homebridge. You can manage Homebridge by navigating to the address displayed in the console.

The Homebridge Config UI X web interface allows you to install, remove and update plugins, modify the Homebridge config.json, and manage other aspects of your Homebridge service.

Login to the web interface by navigating to http://<ip address of your server>:8581. You can access this from any device on your local network.

To find the IP address of your server, you can run:

hostname -I

Review the Configuration Reference section below for important information about managing your installation.

You can safely close the Hyper-V Manager and Virtual Machine windows. The Homebridge virtual machine will continue to run in the background and will automatically start when your computer restarts.

You can access the console again at any time by opening the Hyper-V Manager app and double-clicking on the Homebridge virtual machine.

You can remove the Homebridge Hyper-V Virtual Machine using the Hyper-V Manager program. You will need to stop the VM before you can delete it.

To update Node.js to the latest LTS version, run the following command in the Homebridge terminal:

sudo hb-service update-node

This table contains important information about your setup. Use this as a reference when configuring or troubleshooting your environment.

• For the recommended VM Image installation, see the Homebridge VM Image Wiki
• For general Homebridge help, visit the Homebridge Wiki
• Join the Homebridge Discord community