Room Administration

Last updated: 2025-08-06

Room Upgrades

What's a room upgrade? (Why) should I upgrade my room?

Rooms are a central concept to Matrix: they are where users exchange messages. Each room has a set of rules that describe how a room works, such as setting ID formats, or how certain events interact. These sets of rules form a "room version" so that when rules need to change, it does not mess with the expectations already established in an existing room. When Matrix adds new features, or when bugs emerge, it can be necessary to change those rules. But a Matrix room will not follow the latest rules automatically! To enjoy the new features and the bug fixes, rooms need to be "upgraded". The Matrix way to handle this is to create a new room with the desired settings and create a link between old and new room. The old room is then considered upgraded to the new room.

On August 11th 2025 there was a planned coordinated security release introducing the new room version 12, with a security disclosure following on August 14th. If you are responsible for public rooms, you should make a plan to upgrade those rooms. The rest of this guide will help you to build that plan.

Advanced use cases

Some room settings are immutable without moving to a new version of the room. So, to change the room's end-to-end encryption setting, or the room creator, you would need to upgrade. As Matrix room versions are not ordered, it is possible to "downgrade" or "sidegrade" a room's version, e.g. to go from version 12 to version 12. For example, in rooms up to version 12, you could "sidegrade" to remove admins from a room. Likewise, to adjust creators from room version 12 onwards.

How to upgrade a room

We recommend to read this chapter first in its entirety and make a plan before starting to upgrade rooms. Room upgrades are disruptive for users. You want to get it right first try to cause as little friction to your community as possible.

Prerequisites

When you upgrade a room, the user performing the upgrade needs the permission ("power level") to send a m.room.tombstone event. This might be named differently in client UI, e.g. "Upgrade the room" in Element Web.

Upgrading

Clients that support upgrading rooms usually offer a button or similar in their UI when an upgrade is available. Sometimes the client UI allows you to choose the target room version, but usually it uses the default room version defined by the homeserver.

If the option is missing, the combination of your client and your homeserver's configuration may not recommend an upgrade. Read on to learn how to upgrade anyway.

Advanced upgrading

There are some reasons why your client might not be showing you the upgrading UI despite an upgrade being possible, including:

Your homeserver implementation or admin doesn't advertise support for the room version, via the homeserver's configuration.
Your client only recommends upgrading from or between certain versions.

In these cases you can use e.g. Element Web's /upgraderoom <version> chat command. You can also downgrade and sidegrade in this way.

Limitations

While the Matrix specification is not strict about it, your homeserver will typically perform the room upgrade on a best effort basis, trying to create the new room with settings matching the old room. The decentralised nature of Matrix can lead to circumstances that your homeserver cannot automatically mitigate. The following recommendations can help.

Recommendations

This is a non-exhaustive list of recommendations to consider when planning a room upgrade. Which of these cases apply to your room depends on your specific setup, for example the size of your community.

Choose the right account

You should choose the "right" account on the "right" homeserver to perform your upgrade. The account that starts the upgrade decides which homeserver performs the upgrade. Here are some important factors to guide your choice:

Upgrading a room means that the room members need to receive the info about the upgrade and then join the new room. The homeserver performing the upgrade initially acts as a gateway to the new room. You want to choose a homeserver that is fast and well connected so it can handle all the joins following the room upgrade. If your community centers around a certain homeserver, it makes sense use that one.
Users may have set up aliases - shareable addresses to find the room that are hosted by a specific homeserver. By definition, a homeserver can only update aliases that it hosts. Only aliases on the upgrading homeserver transfer automatically. However, you can (and should) always update the aliases on other homeservers after the upgrade, using respective accounts on these servers.
If your community is using a space to organise its rooms, the user upgrading a room needs at least enough permissions in the parent space to update the reference from the old to the upgraded room.
Room version 12 introduces some changes to room ownership semantics, such as irrevocable full control of the room. For communities, you should use a long-lived, trusted account, such as a moderation bot account, to upgrade your rooms. Using a separate service account to execute the upgrade means that this account will be the creator of the new room with the new special access rights. As a special account, you can manage access to it among your admins outside of Matrix. You could also consider setting up backup accounts on homeservers as additional_creators, in case one of them becomes unavailable.

Bots and integrations

Bots and integrations in your rooms may require additional manual migration steps. After upgrading, reconfigure your bots and integrations for the new room. This is particularly important for any moderation tooling you are using, such as draupnir or mjolnir. Check if your integrations need a configuration update, e.g. supplying them with the new room ID, and check that they have joined the upgraded room. Some integrations also store state in Matrix rooms, so consider if you need to recreate or copy some room state over, as is the case for example with Hookshot configuration.

Room Directories

The published room directory is a per-homeserver index of advertised rooms. As with aliases, each homeserver can only update its own room directory. If your old room is in the room directory, you might have to update the reference to the new room manually, especially on those homeservers that did not perform the upgrade.

Rate limits

Rate limits might apply to your upgrade in several different ways. This means that certain actions, such as creating a room, can only be done a few times before needing to wait.

Homeservers will only allow you to create a certain amount of new rooms within a certain time, so you might get stuck half-way if you have many rooms to upgrade. Using a special account as mentioned above can work around this: some servers allow their admins to specify accounts that are exempt from rate limits. For example, your moderation bot account can be a good candidate for this, as it usually already has exemptions so it can execute many moderation actions in a short amount of time.
Homeservers will only allow you to send a certain amount of invites as well as...
...only allow users to join public rooms at a certain rate. It may make sense for your community to inform your users about this up front.
Homeservers will only allow a single user to join a certain amount of rooms at a time. If your community has a lot of rooms that are being upgraded, your users might receive a lot of room upgrade notifications asking them to join the upgraded room, but they might get rate-limited depending on their homeserver's configuration. You might thus consider sending follow-up pings to the old rooms to make sure everyone got notified about every room and followed the upgrade successfully, since it is easy to lose a room due to the different notification and rate limiting mechanics in play.

Communicate the upgrade plans to your users

There are several situations that users will need to handle on the "receiving" side. For example, there might be aliases, room directories, and spaces referencing your room, which you might not be aware of and that will need to be updated by the respective users.

There are also some clients that do not have support to find and join the upgraded room from the old room. You should send a manual message into the old room with a link to the new room as a workaround for these users. You might consider pinning the message, using a room ping, renaming the old room, and similar methods to make sure your users are aware of the upgrade.

If you're upgrading a room that is not public, you will need to invite the old members or make the new room joinable in another way, so users can join the new room when prompted. Some clients offer an option to automatically invite all users to the new room.

Clients supporting room upgrades

The following lists are not comprehensive. If your client supports room upgrades, please consider contributing to this list.

Sending room upgrades

Element Web/Desktop
Element Classic Android
Fractal
NeoChat
Quaternion
FluffyChat
Cinny

Executing an upgrade using the `/upgraderoom <version>` command in Element Web.

Following tombstones to the new room

Element Web/Desktop
Element X iOS and Android
Element Classic iOS and Android
Fractal
NeoChat
Quaternion
FluffyChat
Cinny
Tammy
Nheko

Significant changes between room versions

You can find comprehensive information about the differences between room versions in the Matrix specification. Here is a short summary of some significant changes.

Upgrading to room version 12

Find a summary of the most relevant changes in the security pre-disclosure on the blog.

Tools and scripts

The Matrix community has created some tooling to aid with performing room upgrades which you might find useful.

References and further reading

Community admins are documenting their experiences about upgrading rooms which can be useful as additional references.