Migrate from Discord to Matrix

How to migrate from Discord to Matrix without an importer

If your community or team on Discord needs its own server, control over retention and identity, and a way to move without an import path, the practical answer is a staged rebuild with a bridge running in parallel. You stand up a self-hosted Matrix homeserver, bridge the Discord channels you care about so members on both sides see the same conversations, and move people over channel by channel. The platform or community owner usually leads this, often with an implementation partner doing the infrastructure, bridge configuration and cutover work. Effort and risk depend on the number of servers, the number of channels and how much history the community wants to keep. Each Discord server you bridge adds channel mappings, permissions to verify and moderation rules to rebuild, and each channel you want to keep history for adds backfill work and a longer validation window. Ask any partner to scope these three counts in writing before work starts, and ask which of them drive the timeline. Plan for the bridge to be fragile in the middle of the move: confirm which features relay both ways in your setup, test replies, reactions, edits and media with a small pilot channel, and agree who owns the bridge when a Discord-side change breaks it. Before you commit, check the homeserver side. Synapse recommends PostgreSQL for production, and recent releases require PostgreSQL 14 or newer and Python 3.10 or newer, so confirm your database and runtime standards with your platform team. Set server_name carefully because it fixes how user IDs and room IDs are written, and decide early whether you want federation at all. An empty federation_domain_whitelist disables federation, and the docs recommend firewalling the federation listener as well. Changing these later is hard, so make the decision before any users are onboarded.

Which Discord features map to Matrix, and which need rework

This table maps the Discord capabilities a community relies on to their closest Matrix equivalents and marks each as clean, needs rework or gap. Read each row as a starting hypothesis to test in a pilot room, since Matrix clients and bridges change between releases. Voice and some community features will likely need a separate design, so confirm those rows before you commit a date to members.

Discord capability	Matrix equivalent	Status	Confirm before migrating
Servers	Spaces grouping related rooms, with a homeserver per organization	Needs rework	Confirm how your Element client displays spaces and how members join them
Text channels	Rooms, including public rooms in a room directory	Clean	Confirm room visibility and directory settings on your homeserver
Threads	Threaded replies in rooms, depending on client support	Needs rework	Confirm thread rendering in Element and in the bridged Discord view
Roles and permissions	Power levels set per room and per user	Needs rework	Map each Discord role to explicit power levels and test each permission
Voice channels	Element Call for group calls, configured separately from text rooms	Gap	Voice needs a separate design, and Element Call availability depends on your deployment
Bots and integrations	Bots built on the Matrix client API, plus bridges for specific services	Needs rework	Most Discord bots must be rewritten or replaced, so inventory them first
Moderation tools	Kick, ban and redaction actions through power levels, with no direct Discord-style automod	Gap	Confirm which moderation features your chosen clients and bots provide
Member lists and invites	Room membership and invite links, managed per room or space	Clean	Confirm invite and join rules on your homeserver configuration

Why there is no direct import from Discord history into Matrix

A server owner cannot pull a community's full message history out of Discord and load it into a Matrix room. Discord's data request tooling is built around the individual user: each member can request a Data Package for their own account, which contains their own activity and content. Those packages are not a channel export, so collecting them from every member would still leave gaps in the record. No importer can rebuild the full channel history from them. Confirm the current scope of these requests in Discord's own help documentation before you write the migration plan, because the plan depends on it.

That limit turns history into a decision the team has to make before cutover. There are three options. The first is a read-only archive kept outside both platforms, where the team stores whatever it lawfully holds in a system it controls and labels it as historical. The second is to relay history forward: the bridge carries messages from the moment it is connected, and the sibling page on bridging explains backfill and its limits. The third is to leave older history in Discord, keep the server readable for a stated period and link to it from the Matrix space. Each option has different owners, costs and retention obligations, so none of them should be chosen by default.

Record the choice per channel, not once for the whole server. Channels that hold support decisions, moderation records or project knowledge often justify an archive, while casual social channels may not. Ask the maintainers of mautrix-discord, listed in the Matrix bridge directory, what history the version you deploy actually backfills, and check Discord's terms for copying member content into another system. Assign a named person to own the archive, decide where its access controls live, and set a date for reviewing whether the bridge can be switched off.

What data and integrations to move, and what to rebuild

A Discord community does not move as a single export. Each kind of data follows a different path: some is relayed by the bridge during the transition, some must be archived by hand, and some is rebuilt on the Matrix side. The cards below set out which path applies to each item and what to confirm before cutover.

Member identities and user IDs

Matrix identifies every account as @localpart:server_name, so the server_name setting fixes the domain that appears in every user and room ID. Discord user IDs do not carry over. Bridged Discord members appear through puppet accounts that the bridge creates on your homeserver, so decide the naming pattern before the bridge goes live. Confirm how each member will authenticate, since the Synapse configuration manual documents OpenID Connect, SAML2 and CAS options for single sign-on, and confirm the server_name value cannot change later without rebuilding identifiers.

Room and channel structure

Discord categories, channels and roles have no one-to-one Matrix equivalent. Each text channel typically becomes a Matrix room, and categories are usually rebuilt as spaces or as naming conventions. Bridged rooms reflect the Discord channel layout while the bridge runs, so plan which rooms stay bridged and which are retired. Permissions must be recreated by hand using Matrix power levels, and voice channels are not relayed. Confirm the room list and the power level for each moderator role before inviting members.

Message history decisions

The bridge relays messages posted while it runs, so history begins at the bridge start date unless you request backfill. Discord's per-user Data Package contains only the requesting user's own messages, so it cannot rebuild a server's full channel history. Decide whether older history is archived as static files for reference, or left in Discord. Confirm with the bridge documentation how far backfill reaches and whether it covers every channel you need.

Media and attachments

Attachments posted in Discord are served from Discord's CDN, and links can expire, so media must be handled deliberately. The bridge relays media for messages it sees, which places copies on your homeserver's media store. Check the media retention and size limits configured on your homeserver, and decide whether older attachments are downloaded into an archive. Confirm how the bridge handles files sent before its start date, since those may remain as dead links.

Bots and webhooks

Discord bots, slash commands and incoming webhooks do not transfer. Each one must be rebuilt as a Matrix bot, a webhook service or a bridge integration on your side, with its own account and permissions. List every integration your community depends on, including moderation bots and announcement feeds, and assign an owner for each. Confirm which replacement your team can operate and maintain after the Discord integration is switched off.

Moderation rules and retention

Discord AutoMod filters, timeouts and ban lists are configured inside Discord and do not export. Rebuild the rules as written policy, Matrix power levels and ban lists maintained by your moderators, and decide how long your server retains messages and reports. Because your homeserver holds the data, retention and deletion become your responsibility. Confirm who can act on reports, how bans propagate to bridged accounts, and where moderation logs are kept.

The migration sequence from inventory to decommission

This sequence moves a Discord community to a self-hosted Matrix homeserver in stages, so members keep one shared set of channels while the move happens. Each phase ends with a named artifact that the next phase depends on, and the Discord server is only shut down after the Matrix side has been tested and accepted.

Inventory servers, channels, roles, bots and members
Before anything is built, the server owner and moderators record every channel and category, the role hierarchy and permissions, each bot and webhook with its purpose, and the members who hold moderation roles. Note which channels carry the most traffic and which hold pinned or reference material that people will ask about after the move. The output is a written inventory signed off by the community leads, with a decision for each channel: bridge, archive, or retire. The step is complete when every channel in the inventory has one of those three decisions.
Build a test Synapse deployment and pilot one channel
Deploy a non-production Synapse homeserver on infrastructure you control, with PostgreSQL as the database (Synapse recommends PostgreSQL for production). Configure the server_name value carefully, because it fixes how user and room identifiers are formed and is difficult to change later. Install the mautrix-discord bridge and connect it to a single low-risk channel, then invite a small group of testers to confirm that messages, replies, reactions and media relay as expected. The output is a pilot report listing what worked, what broke, and what the moderators must do differently. Take a database backup before each configuration or version change, because Synapse upgrades can be hard to roll back due to database schema changes between releases.
Run a parallel period with the bridge in both directions
Extend the bridge to the remaining channels in your inventory so that members on Discord and on Matrix see the same conversations. Set moderation and role rules on both sides, since the bridge does not replicate your Discord role model automatically, and assign Matrix moderators before opening access. Track bridge errors, missed messages and member questions in a shared log, and fix them before widening access. The output is a stable bridge with a documented list of known gaps, such as features the bridge does not carry, that members have been told about. Keep the database backup routine running throughout this phase.
Cut over with a published date and rollback plan
Announce a cutover date to members, state which channels become the primary location, and explain where new messages should go after that point. Write a rollback plan that names who can reverse the cutover, which backup is restored, and the conditions that trigger a reversal. Keep the Discord server readable during cutover so members can check older context. The output is a signed cutover record and a tested restore from the latest database backup, showing that the rollback path works before it is needed. Confirm the restore process in a separate environment first.
Decommission the bridge and retire the Discord server
After the Matrix community has run stably for the agreed period, remove the bridge from channels that no longer need relaying and stop its service. Archive the Discord server exports you made during the inventory and cutover, and record which channels were archived rather than migrated. Then retire the Discord server, or leave it as a read-only pointer to the new Matrix space if members still arrive from old links. The output is a decommission record listing stopped services, archived data locations, and the final state of the Discord server. Ask your administrators to confirm that backups and access logs are retained according to your own policy.

What drives the cost and duration of a Discord to Matrix move

This table compares the main drivers of a Discord to Matrix move, how each one moves cost or effort, and whether the cost is one-time or recurring. Read it as a checklist for scoping: the drivers with the widest spread are history retention, bridge count and identity requirements. No prices or durations are given, so ask for a written scope before comparing quotes.

Driver	Why it changes cost or effort	How to keep it down
Number of servers and channels	Each server and channel needs room mapping, bridge configuration and permission checks, so effort grows with the channel count rather than the member count.	Consolidate low-activity channels before the move and map only the rooms that will carry active traffic.
Retained history	Discord does not give a server owner a full history export, so keeping older messages depends on a separate collection and import effort, which is hard to size without a sample.	Decide which history is worth keeping, and archive the rest as read-only exports with a documented retention rule.
Bridge and bot count	Each bridge or bot needs installation, credentials, monitoring and upgrades, and each one adds a recurring maintenance item.	Run only the bridge the transition needs and retire it on a fixed date agreed in writing.
Identity and SSO requirements	Adding OpenID Connect, SAML2 or CAS to Synapse adds integration work with your identity provider and a support load for account issues.	Start with local accounts for a small pilot, then add SSO once the membership list is stable.
Voice and video needs	Voice channels are not part of the Matrix chat move, so any call service adds a separate build, hosting and support scope.	Confirm early whether members need voice, and scope any calling service as its own item.
Hosting footprint and worker scaling	A production Synapse normally runs on PostgreSQL, and adding workers brings in Redis for replication, so both add hosting and monitoring cost.	Size from measured load after the pilot, and confirm PostgreSQL and Python versions against the Synapse upgrade notes before choosing a host.
Number of moderators to train	Moderators need training on Element, room permissions and the bridge, and every new moderator repeats that training.	Write short role guides and train a small group first, then use them as trainers for the rest.
One-time versus recurring costs	One-time: scoping, design, build, migration and training. Recurring: hosting, Synapse upgrades, bridge maintenance and support.	Ask each quote to show both groups separately, with upgrade and support terms written in.

What usually goes wrong when a community moves to Matrix

A Discord-to-Matrix move usually fails at the edges rather than in the core server. The cards below cover the expectations, bridge operations, identity mapping, moderation, upgrade and federation risks that teams most often underestimate during a parallel run.

History the bridge cannot supply

Members often assume that Matrix will show everything they posted on Discord. The bridge relays messages from the point it is connected and can backfill only what it is able to read, so older Discord history stays on Discord. Before cutover, decide what gets archived outside both platforms, tell members in writing what will and will not carry over, and confirm the backfill limits of the bridge version you deploy. Ask your implementation partner to document the exact cutoff date.

Bridge downtime during parallel runs

During the transition, members on either side depend on the bridge. If the bridge process, its database or its Discord connection fails, messages stop flowing and users may believe the community is split. Run the bridge under a process supervisor, monitor its connection state and set an owner who answers for it. Test a restart and a full rollback in a staging copy before the parallel period begins, and write down the steps to switch the bridge off without losing messages already on Matrix.

Accounts and display names that do not map

Discord usernames, nicknames and numeric IDs rarely line up with Matrix user IDs such as @user:example.com. Duplicate names, changed handles and members who want a different display name cause confusion in rooms and in moderation logs. Decide the naming rule before the bridge goes live, including how Discord identities appear as bridged users, and confirm how the server_name setting will fix identifiers for the life of the deployment, because changing it later is disruptive.

Moderation gaps during cutover

Discord bots, role-based permissions and automod rules do not transfer to Matrix. During cutover, bans, mutes and role assignments may apply on one platform but not the other, which leaves abuse channels open. Map every Discord role to a Matrix power level, assign moderators on the Matrix side before members are invited, and keep a shared log of actions taken during the parallel run. Confirm which moderation actions the bridge propagates and which must be repeated manually.

Synapse upgrades that break the bridge

Synapse and the bridge each release on their own schedule, and Synapse upgrades can change database schemas and drop support for older Python or PostgreSQL versions. The upgrade notes warn that rolling back can be difficult after schema changes. Pin the Synapse version, read the upgrade notes before each change, take a database backup, and test the bridge against the new Synapse version in staging before you upgrade production. Record which bridge and Synapse versions are known to work together.

Federation exposed without a whitelist

A homeserver that is reachable on the federation port can exchange events with any server that discovers it, which may not match the community's intent during a migration. Set federation_domain_whitelist to the domains you choose, or to an empty list if you do not want federation, and firewall the federation listener as the Synapse documentation recommends. Review the list whenever a partner server is added, and confirm the port and delegation settings with your network team before opening the server to members.

How the move differs for a small community, a company and a public community

A small community run by volunteer moderators usually has a handful of channels, a single admin team and members who expect accounts to work the same way they did on Discord. The scope is narrow, so the main work is getting the homeserver running, recreating rooms and roles, and getting members to log in without friction. Identity work is light, since local Matrix accounts are often enough. Federation is the main decision: a community that wants to stay private can restrict it, while one that wants to talk to other Matrix communities needs the federation listener reachable.

Scope: a few rooms, one moderator group and a short list of members to onboard.
Identity: local accounts with a registration process the admins control, rather than a corporate directory.
Federation: decide early whether to limit it with federation_domain_whitelist or leave it open.
Moderation: keep power levels simple and write down who can kick, ban and redact messages.
Cutover: run the bridge for a short overlap, then announce a fixed date for moving conversations.

Before starting, confirm with your volunteers who will hold server admin access and how the server will be backed up if the person who set it up steps away.

A company moving internal team channels has to treat the Matrix server as business infrastructure. Identity is the largest piece of work: accounts should come from the corporate directory, offboarding should disable access in the same process as other systems, and retention and audit expectations need to be written into the design. Synapse supports single sign-on through OpenID Connect providers (oidc_providers), SAML2 (saml2_config) and CAS, so the identity provider in use determines the configuration path. Confirm the exact setup with your identity team before committing.

Identity: connect oidc_providers, saml2_config or CAS to the existing provider, and test deprovisioning.
Federation: most companies restrict it to a known list of domains or disable it entirely.
Retention: define how long messages and attachments are kept, and who can change those settings.
Moderation: map Matrix power levels to existing support and HR roles rather than inventing new ones.
Cutover: move teams in groups, starting with lower-risk channels, and keep the bridge running only for the period agreed in advance.

Ask your security and compliance leads which retention and audit evidence they need before the first production room is created, because changing that later is harder.

Whatever the size of the community, the platform decisions are the same, but the order and weight of them change. A small team can settle most of them in an afternoon, while a company or public community needs written decisions that its own governance can review. Every tab depends on the same base: a PostgreSQL database, a correct server_name, a tested backup and a clear rollback plan. Rolling back Synapse can be difficult because database schemas change between releases, so the upgrade path should be tested on a copy before production. The right choice of tab is less about the size of the community and more about who will be answering for the server when something goes wrong.

Database: use PostgreSQL for production, with the version required by the release you deploy.
Naming: set server_name before any users exist, because it fixes how identities and rooms are named.
Backups: test restoring a full backup, not just taking one.
Upgrades: rehearse each Synapse upgrade on a copy and read the upgrade notes first.
Ownership: name the people accountable for identity, moderation and the server itself.

Before you choose a tab, confirm with your team who will own each of these items and whether that ownership is written down.

Questions buyers ask before they move from Discord to Matrix

Can our team move a Discord community to Matrix without outside help?

Yes, many teams with a Linux operator and some Matrix experience can run a homeserver and a bridge themselves, but the harder part is usually the community work, not the software. Your team must size the server, set up PostgreSQL and Redis if you scale out, configure the server_name, handle TLS and federation, and maintain upgrades. Discord's own Data Package does not give you the server's history, so plan the member communication and channel mapping yourself. An outside implementation partner can take that work under a written scope, which is one option among several. Confirm the current requirements in the Synapse documentation before you commit.

What does the community owner need to provide during the move?

The owner decides the things a server cannot decide for you. You need a list of channels and roles to recreate, a naming scheme for Matrix rooms and spaces, moderators who will run the new server, and a clear rule for who may create rooms. You also need a decision on which members get accounts, how identities are verified, and whether the community will federate with other servers. Expect to answer these questions before any technical work begins, because the answers shape the configuration. Document them so the migration can be reviewed later.

Can we import our past Discord message history into Matrix?

Not through a standard importer, and the Discord per-user Data Package does not hold a community's full history. It contains a single user's own messages, servers and activity, so a server owner cannot rebuild channels from it. The bridge carries new traffic from the point you connect it, and backfill depends on what the bridge and Discord expose at the time. Treat older history as something you archive separately if you need it, and confirm the exact limits in the mautrix-discord documentation and Discord's data export help before you promise members anything.

How long should the bridge run before we switch it off?

The bridge should run until members have moved their daily conversation and the channels on Matrix are the place people expect to find activity. The length depends on how many members are still active on Discord, how many channels you bridge, and how much you rely on voice, which the bridge does not replace. Set a switch-off date only after you have measured activity on both sides, and agree it with moderators in advance. Keep the bridge's logs and its database backed up while it runs, since it is part of your running system.

What should a quote for this migration include?

A useful quote lists each deliverable in writing: the server and bridge architecture, hosting and sizing assumptions, database and Redis setup, identity and SSO configuration, the channel and role mapping, the bridge rollout and switch-off plan, backups, upgrade procedure, documentation and handover. It should name what is excluded, such as voice infrastructure, history archiving or member support. Ask for the assumed number of users, channels and bridged servers, because those drive effort. DeployOpen plans and implements these engagements as fixed scope, with deliverables and timelines agreed in writing before work starts, and quotes follow from that scope.

Is a self-hosted Matrix server the right choice for a community that depends on voice?

It depends on how central voice is to your community. Matrix supports calls, but a bridge does not carry Discord voice channels, and you would need to plan and operate call infrastructure separately, which Element's packaging may help with. Communities that live in voice rooms often find the move harder than text-only communities, and you should test your most active voice use cases before deciding. Confirm current call support and its operating requirements in the Element Server Suite documentation and the Matrix documentation before you choose.

How DeployOpen scopes, runs and supports a Discord to Matrix migration

DeployOpen plans, implements, integrates, hardens, backs up, documents and supports self-hosted open-source platforms inside your own infrastructure. For a Discord to Matrix move, we start with a written scope that fixes which channels, roles and bridge behavior are in play before any server is built.

How we scope

Inventory the Discord servers, channels, roles and bots that the community relies on today.
Agree in writing which channels the mautrix-discord bridge will relay and for how long.
Confirm the Matrix homeserver hosting location, database, identity sign-in and retention rules before build starts.

How we build

Deploy the Synapse homeserver and Element clients in your cloud accounts or data center.
Configure the bridge so members on both sides see the same channels, with reactions and threads tested.
Test federation settings, moderation roles and backup restores against the agreed scope.

How we hand over

Document the bridge configuration, channel mapping and the steps to switch the bridge off.
Provide runbooks for user onboarding, room administration and Synapse version upgrades.
Walk your administrators through the cutover checklist and the Discord history limits that apply.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Plan Synapse and bridge upgrades around release notes, since rollbacks can be difficult.
Confirm the support boundaries, response expectations and ownership of the bridge in the written scope.