Migration of Python-Matter-Server Docker container to Matter.js with HA 2026.2?

goonie · January 30, 2026, 6:27pm

I read about HA 2026.2 to replace Python-Matter-Server with Matter.js. I currently run HA in a Docker container, and Python-Matter-Server in another container.

What’s the way to migrate? Will there be a new Docker image that contains Matter.js and is able to automatically migrate data from Python-Matter-Server? Or will Matter.js be included with the HA Docker image in future?

wmaker · January 31, 2026, 1:01am

Both python and node.js versions come with the AddON. You can enable the Beta version of the Matter Server AddOn (and then restart the AddOn) to try out Matter.js, and it should auto-migrate. You can also subsequently disable the Beta version (and restart the AddOn) to get back to the python based version.

odwide · January 31, 2026, 5:16pm

Same question here. HA is migrating from the legacy Python-based Matter Server to a new JS-based version (Matter (.js) Server). They say that the new version is a “drop-in” replacement. The migration is seamless for users of the Matter Server add-on; however, is it so for installations that run the Matter Server (Python) on a remote container? And if so, what’s the migration route? I guess we simply create the new image pointing it at the same storage used by the old one.

Does anyone know or has tried?

vesalius · January 31, 2026, 7:53pm

github.com/matter-js/matterjs-server

ALPHABETATESTS.md

a44245e65

# Alpha/Beta Test of the New Matter Server

## Overview of Test Phases and Their Goals

### Phase 1: Alpha Test of the New Matter Server (starts Mon 12.01.2026)

This test phase involves a separate installation of the new Matter Server and does not provide an updated Home Assistant add-on or integration. This means it requires some advanced knowledge on how to install and run the server and how to get the relevant files.
Please see detailed instructions [below](#manual-test-instructions).

The main goals of this phase are to:
* Validate the basic functionality of the new Matter Server based on matter.js
* Ensure that the migration from the python-matter-server storage format to the matter.js format works as expected
* Verify that the server connects to all online nodes in the fabric, subscribes to all data, and works as expected
* Confirm that the dashboard shows the correct values for all nodes and works correctly, including OTA, binding setup, and device management (commission, remove nodes)
* Verify that when adding or removing nodes, the `<long-number>.json` file gets updated
* (If possible) Add the temporary server location as a Home Assistant Matter integration to a (test?) HA instance and validate functionality there too (all entities are discovered correctly, data updates, etc.)
* (If possible) After deleting/adding nodes in the Matter Server, copy back the `<long-number>.json` to the Python server, and new nodes should connect there too and show up in HA; deleted nodes should disappear from HA

### Phase 2: Official Release for all "Beta" HA Addon Users (released 22.01.2026)

This file has been truncated. show original

The current migration route for docker installs is linked above, I am sure this will be similar or easier once the beta is over. With first start of the beta importing the python server data takes a while, but after that the Matter-JS server is much faster in every way already.

odwide · January 31, 2026, 8:07pm

Excellent. Thanks!

bigdvette · February 28, 2026, 4:48am

I migrated about a week ago. I use docker swarm with disk connections on a NAS. The only way I could get this to “upgrade” was to move the files locally to the one of the swarm node and then it flew through the first time upgrade. I notice it creates a lot of files. The server seems very disk speed sensitive. My AS was doing a snapshot prune and lights would take forever to respond and have HA update. Is the new server supposed to be so disk speed dependent? I hadn’t had problems with the older python server, but it does not use all the files. have about 140 matter devices. has anyone else seen this behavior?

odwide · March 1, 2026, 2:14am

I migrated last week too. Painless, and have seen no issues. But my storage is all local and I only have about 5 Matter devices.

vesalius · March 1, 2026, 4:05am

You could ask the Main Dev over on the Discord channel dedicated to the new Matterjs-server. He is very responsive.