Skip to content

How to migrate your Matrix account to a new Matrix homeserver

This guide is not about moving from Mattermost to Matrix

If you want to move your content from Mattermost to Matrix, see How-to move from Mattermost to Matrix instead.

This guide explains how to migrate a Matrix account from one homeserver to another while preserving message history and room memberships.

Replace old.server and new.server with the actual homeserver domains throughout this guide.

The process consists of two phases:

  1. Prepare the old account – export keys and note down rooms/contacts.
  2. Set up the new account – register, import keys, re-join rooms.

Prerequisites

  • Access to your current Matrix client (Element Web, Element Desktop, or similar).
  • Your current Matrix ID in the form @username:old.server.
  • Credentials for the new account on new.server (or ability to request one).

Phase 1 – Prepare the Old Account

1. Clean up unwanted rooms

Before migrating, leave any rooms you no longer need. This keeps the new account tidy and speeds up the migration.

  1. Open your Matrix client and go to your room list.
  2. Right-click (or long-press) each unwanted room and select Leave room.

2. Note down important rooms and direct messages

There is no automatic way to transfer room memberships. Write down (or screenshot) the list of rooms and direct-message contacts you want to keep.

For each room, note:

  • The room address (e.g. #roomname:server.example).
  • Whether it is a direct message (DM) and the other person’s Matrix ID.

3. Export encryption keys

If you use end-to-end encrypted (E2EE) rooms, you must export your key backup before switching accounts, otherwise old encrypted messages will be unreadable on the new account.

In Element Web / Element Desktop:

  1. Go to All Settings () → Encryption.
  2. Under Advanced - Encryption details, click Export keys.
  3. Enter a strong passphrase and save the exported .txt file in a safe place.
  4. Do not store this file on a shared drive or send it by email.

Recovery key

See also How-to handle the recovery key for general guidance on safeguarding your encryption material.

To avoid confusion during migration, sign out of all devices except the one you are currently using:

  1. All Settings () → Sessions → Other sessions.
  2. Go through the list and click Manage this session for each entry.
  3. On the next page click Remove device.

Phase 2 – Set Up the New Account

5. Request or create the new account

Once your new account is ready, you will receive your new Matrix ID: @username:new.server.

6. Log in to the new account

Open your Matrix client and log in with the new credentials using the new homeserver URL. If you are using the Element app, see How-to configure Element client.

7. Import encryption keys

Restore the encryption keys you exported in step 3 so you can read old encrypted messages:

In Element Web / Element Desktop:

  1. All Settings () → Encryption.
  2. Under Advanced - Encryption details, click Import keys.
  3. Select the .txt file from step 3 and enter the passphrase.
  4. Confirm the import.

Note

Element does not display imported keys anywhere in the UI – there is no key list to confirm success. Instead, verify the import worked by opening an old encrypted room: messages that previously showed a padlock icon and “Unable to decrypt” should now be readable. If they are, the import was successful.

8. Invite the new account to private rooms and direct messages

While still logged in to the old account, invite the new account to all rooms and direct messages where you have permission to invite others.

Tip

You can keep both accounts logged in simultaneously by using a private browser window or a second client for the old account.

  1. Open the room or direct message with the old account.
  2. Room info → Invite → enter @username:new.server.

Note

It may take a few minutes for the invitation to appear on the new account.

9. Transfer room admin rights (if applicable)

If you are an admin or moderator in rooms, transfer those rights to the new account before deactivating the old one:

  1. Open the room with the old account.
  2. Room info → People.
  3. Promote @username:new.server to the same power level you currently have.

10. Re-join other rooms

With the new account, join all remaining rooms you noted in step 2:

  • Rooms invited to in step 8: Accept the pending invitation.
  • Public rooms: Search for the room address (e.g. #roomname:server.example) and join directly.
  • Private rooms where you could not invite yourself: Search for the room and request access, or ask the room or Space admin/moderator to invite @username:new.server.
  • Direct messages: Accept the pending invitation from step 8. For contacts you could not invite yourself, start a new DM by searching for their Matrix ID.

Note

If a room is configured to only show history from the point of joining or invitation onwards, the new account will not be able to see messages sent before the invitation in step 8 – even if those messages are not encrypted. This is a room-level setting controlled by the room admin and cannot be bypassed during migration.

11. Deactivate the old account

Once you have verified that the new account is working correctly:

  1. Log in to the old account in Element.
  2. Go to All Settings () → Account → Manage account → Delete Account. This opens the Matrix Authentication Service (MAS) in your browser.
  3. Follow the confirmation steps in MAS.

Deactivation is irreversible

All rooms the old account was a member of will show the account as having left. Confirm that all important rooms and contacts have been migrated before proceeding.

Troubleshooting

Issue Solution
Old encrypted messages unreadable Re-import keys (step 7); check that the passphrase is correct.
Cannot join a private room Ask an existing member to invite @username:new.server.
Key import file not accepted Ensure the file was exported from Element and not modified.
Old account still shows as active Complete deactivation via the old homeserver’s account management (step 11).