How to migrate from Slack to Mattermost
Move Slack to self-hosted Mattermost: get the export your plan allows, convert it with mmetl, import history and files, rebuild integrations and cut over.
In short
- Slack exports public channels on every plan; private channels and direct messages need the full export, which Business+ owners apply for and Enterprise org owners request from Slack Support.
- Mattermost converts the export with mmetl and imports it with mmctl: channels, threads, reactions and files arrive with their timestamps, and the files are fetched from the export’s links.
- Integrations are not in the export: Slack-format incoming webhooks move to a new URL, and Slack apps and workflows are rebuilt as Mattermost bots or n8n workflows.
- The import is idempotent, so repeated export and import cycles carry new messages across during the parallel run without duplicating what is already there.
On this page (12)
Moving from Slack to Mattermost is an import with a rebuild around it. Mattermost publishes the tools that convert a Slack export and load it, so channels, threads, reactions and files arrive with their original timestamps. What a Slack export leaves out is rebuilt by hand: apps, workflows and webhooks. And what the export contains depends on your Slack plan, which is why the work starts there. This guide covers the order we run it in when we move a team, and the places it usually goes wrong.
Why teams move from Slack to Mattermost
Three reasons come up again and again.
- The history sits in your database. Chat is where things get said: incident threads, customer names, credentials pasted in a hurry. With Mattermost on your own machines, every message is in your PostgreSQL database and every file in your object storage, in the location you choose.
- Export and retention on your terms. In Slack, which conversations you may export depends on the plan you pay for, and on the Free plan messages and files are kept for one year. With Mattermost, the database is yours to back up, query and keep for as long as your rules require.
- Reachable only on your network. Mattermost can answer on a private network only, with the desktop and mobile apps as the way in. The internet never sees a login page.
What you give up is Slack’s app directory, where most tools have a ready-made integration, extras such as huddles, clips and canvases, Slack Connect channels shared with other organisations, and the fact that Slack runs the platform. Also plan for the licence: single sign-on with the full history, guest accounts and automated retention are features of the paid Mattermost plans.
Step 1: get the export your Slack plan allows
Everything that follows is limited by this file, so settle it first.
| Slack plan | Who can export | What the export holds |
|---|---|---|
| Free | Workspace Owners and Admins | Public channels, with file links from the last 90 days |
| Pro | Workspace Owners and Admins | Public channels and their file links |
| Business+ | Workspace Owners and Admins; Owners apply for more | Public channels, or all conversations once approved |
| Enterprise | Org Owners and Admins, once Slack Support enables tools | All conversations, by workspace, member or type of chat |
- Start the standard export. Slack documents the steps in Export your workspace data. In the desktop app, click Admin in the sidebar, select Workspace settings, then Security, then Import & export data, and open the Export tab. Choose the date range and click Start Export. Slack emails you when the export is ready, and you download the ZIP file from the workspace’s export page.
- Apply for the full export if you need private channels and direct messages. On Business+, use the submit an application link on the same tab and choose the export type. The Workspace Primary Owner has to approve the application, and Slack Support contacts them by email before reviewing it. On Enterprise, org owners request the export tools from Slack Support. Start this first: the rest of the plan depends on the answer.
- Keep the archive exactly as it came. Mattermost warns that unzipping and rezipping a Slack export can change its layout and break the conversion.
The ZIP holds users.json and channels.json, and in a full export groups.json, dms.json and mpims.json for private channels, direct messages and group DMs, plus a folder per conversation with one JSON file per day and a canvases.json file. It holds no files. Slack’s own description is that its exports “do not contain any files from the workspace”: each message carries links to its files, and the conversion downloads them from Slack, so the workspace has to be open while it runs. On the Free plan, file links cover the last 90 days only, and what is older than a year has already been deleted.
Step 2: inventory channels, integrations and people
The export records what was said. It does not record what still depends on Slack. Before any import, list:
- Channels, each with an owner. The daily files in each channel’s folder show when it was last used; archived channels import as archived.
- Apps and integrations. The Installed Apps and Custom Integrations lists on Slack’s app management page show every app, bot and custom integration. Note what each one does, who owns it and where it posts.
- Workflows built in Workflow Builder, with their triggers and owners.
- Webhook senders: monitoring, CI pipelines and scripts that post into Slack. Every one of their URLs changes.
- Guests and Slack Connect: single-channel and multi-channel guests, and channels shared with other organisations.
- The extras: custom emoji, canvases and user groups, none of which comes across.
Each line ends with a decision: import, rebuild, replace or drop. Channels nobody uses any more are best archived in Slack before the export: they import as archived, readable but closed to new posts.
What the Mattermost Slack import brings across
Imported
- Public and private channels, archived ones as archived
- Direct messages, and group messages of up to eight people; larger group DMs become private channels
- Posts, threads and replies, with their original timestamps
- Reactions, by emoji name
- File attachments, downloaded from the export’s links
- Users with name, email and title; deactivated users as deactivated accounts
Not imported
- Slack apps, Block Kit, Events API subscriptions and Workflow Builder
- Incoming and outgoing webhooks and slash commands
- Slack Connect, as a shared channel
- Custom emoji images, canvases and user groups
- Profile pictures, statuses and passwords
Step 3: run a test import on a staging server
Mattermost recommends a fresh server and a first run in staging. Build it as production will be: PostgreSQL, S3-compatible object storage for attachments, and free disk of at least three times the export’s size for the conversion. The tools are Mattermost’s own: mmetl converts the export into Mattermost’s bulk import format, and mmctl loads it. The import job is part of the open-source server.
Before the first import, set the server up for it:
- Create the destination team, with a lowercase, hyphenated name, and allow any user with an account on the server to join it. Never import into a team people already use.
- Raise the maximum users and channels per team above what the export holds.
- Keep sign-up and sign-in with email switched on while the import runs.
- Raise the maximum file size above the largest Slack attachment.
- If you use Elasticsearch, switch indexing off during the import and rebuild the index afterwards.
Then convert, check and import, following Mattermost’s Slack migration guide. mmetl runs on Linux and macOS.
# Check the export without writing anything, with the same flags as the real run
mmetl transform slack --team acme --file slack-export.zip \
--output mattermost_import.jsonl --bot-owner admin --allow-download --dry-run
# Convert it, downloading attachments from the export's file links
mmetl transform slack --team acme --file slack-export.zip \
--output mattermost_import.jsonl --bot-owner admin --allow-download
# Package, validate, upload and import
zip -r mattermost-bulk-import.zip data mattermost_import.jsonl
mmctl import validate ./mattermost-bulk-import.zip
mmctl import upload ./mattermost-bulk-import.zip
mmctl import list available
mmctl import process <name-from-the-list>
The dry run exits with an error on anything that would fail. Give it the same flags as the conversion: without --allow-download, it reports every attachment as missing, because none is in the archive. --bot-owner names the Mattermost user who owns the bots that posted in Slack, so their messages keep an author. For a large archive, Mattermost’s guide copies the file to the server and runs mmctl import process --bypass-upload in local mode instead of uploading it. An Enterprise organisation’s export is first split per workspace with mmetl grid-transform, and each workspace’s archive is then converted on its own, for the Mattermost team it goes into.
Read the log mmetl writes in the working directory, transform-slack.log, for warnings about content it skipped. Then ask the leads of your busiest channels to open them in staging and check that threads, files and mentions read correctly.
Step 4: map users and sign-in
Users arrive with the name, email address and title from users.json. Deactivated Slack accounts arrive deactivated, with their channel memberships, so their old messages keep an author. If a user has no email address, mmetl stops and names them; fix the record, or give mmetl --default-email-domain to build one from the username.
Check the email addresses against your directory before the import. They are what lands each person’s history under the right account once they sign in.
Passwords do not move. Imported accounts get a generated password nobody knows, and people activate their account through Password Reset on the Mattermost login page, with the email address from the import. With single sign-on, which with an imported history needs a paid Mattermost plan, accounts follow your directory instead:
- SAML, through Keycloak or Entra ID. After the import,
mmctl user migrate-auth email saml saml-users.jsonmoves the imported accounts to SAML in one pass. The file lists each email address and username as the identity provider holds them, and each email must match an imported account. For a large workspace this is the cleanest route. - OpenID Connect, including Entra ID.
migrate-authonly moves accounts to SAML or LDAP. With OpenID Connect, each person switches their own account’s sign-in method once before signing in through the identity provider.
Guests need a decision of their own. mmetl imports them as Mattermost guests by default, which works only where guest accounts are licensed and enabled. Without that, import them as regular members with --guest-handling=user, which gives them full user permissions, or leave them out with --guest-handling=skip, which also drops their posts. Profile pictures and statuses do not come across; people set their own.
Step 5: rebuild integrations and webhooks
Integrations are not in the Slack export, so there is nothing to import. Work through the inventory from step 2.
| Slack | Mattermost |
|---|---|
| Incoming webhook | Incoming webhook, which accepts Slack-format payloads |
| Custom slash command | Custom slash command, compatible with Slack’s format |
| Outgoing webhook | Outgoing webhook, recreated |
| Slack app or bot | Bot account and the REST API, or the vendor’s own plugin |
| Workflow Builder | n8n workflow posting through a webhook or a bot |
| Huddle | Calls: one-to-one in Team Edition, group calls on paid plans |
| Slack Connect channel | Guest accounts on a paid plan, or a federated Element room |
| Custom emoji | Re-added under the same name, in lowercase |
| Canvas | Downloaded from canvases.json before Slack closes |
Incoming webhooks keep their format
Mattermost translates Slack-format webhook payloads, so most alerting needs only a new URL. Create each webhook from the product menu under Integrations, Incoming Webhooks, point the sender at the new address, and keep the Slack webhook live until the first message has arrived in Mattermost. A few things differ: Slack’s single-asterisk bold must become **bold**, <#CHANNEL_ID> does not link to the channel, and <!everyone>, <!group> and the mrkdwn, parse and link_names parameters are not supported. Senders that set their own name or icon need the System Console settings that let integrations override usernames and profile picture icons.
Apps and workflows are rebuilt
Interactive Slack apps, Block Kit messages, Events API subscriptions and Workflow Builder have no counterpart to import into. For a tool from Slack’s directory, check whether its vendor publishes a Mattermost integration. Your own apps are rebuilt against Mattermost bot accounts and its REST API. Workflows usually become n8n workflows that post to Mattermost through an incoming webhook or a bot. Rebuild what people still use, with an owner named for each.
Emoji and canvases
Reactions arrive by emoji name, but custom emoji images are not in the export. Re-add each custom emoji in Mattermost under its Slack name, in lowercase, and the old reactions display again. Canvases are not imported at all: download the ones you need from the links in canvases.json while Slack is still open.
Step 6: run both in parallel, then cut over
Mattermost describes repeated export, transform and import cycles during a phased cutover as a supported pattern, and its import is idempotent: posts already imported are not created twice. That is what makes a parallel run safe.
The cutover, in order
- Clients: Desktop and mobile apps are installed and pointed at the Mattermost server before the day, with sign-in tested on each.
- Integrations: Webhook senders and rebuilt workflows switch to Mattermost one by one, each checked on its first message.
- Freeze: On the day, archive the moved channels in Slack. Archived channels are closed to new activity and can be unarchived if you need to roll back.
- Final import: A last export is converted and imported into the same team; posts already there are skipped.
- Close: Slack stays open for its links and files until people stop needing them, and a final full export is kept as your record.
Two details catch teams out. Slack’s #general channel cannot be archived, so post the switch-over notice there. And the imported messages keep their original Slack links, which work only while Slack is accessible: close the workspace at the next renewal, not on cutover day.
Running Mattermost in production
A migrated workspace needs more than the application server.
- PostgreSQL for every message, channel and user, backed up daily.
- S3-compatible object storage for attachments, kept apart from the database so each can be sized and restored on its own.
- An SMTP relay for invitations, notifications and the password resets that imported users rely on.
- Push notifications. Mobile notifications pass through a push proxy run by Mattermost, unless you run your own proxy with your own build of the mobile apps.
- Retention. Mattermost keeps history until someone deletes it. Automated retention policies and compliance exports are Mattermost Enterprise features.
Pilae operates Mattermost this way, with the database and file storage separated from the application from the first day, daily encrypted backups stored at a second site in the same jurisdiction, and on Pilae’s Enterprise plan a restore test every month, recorded in the console. It runs on your premises or on dedicated machines in Pilae Cloud, answering on your private network with one hardened gate for mobile clients. The Pilae Agent plans each upgrade, takes a verified backup and applies it in your window once you approve. If you are still comparing options, see our page on Slack alternatives.
Let Pilae run the move
Pilae runs Slack to Mattermost migrations at a fixed price: the export, including the application for private channels where you need it, the inventory, a test import, single sign-on, the integration rebuild, the parallel run and the cutover. Where your requirements need a paid Mattermost plan, the licence is named in the proposal. Then we operate Mattermost for you with backups, monitoring and upgrades under one contract. See migration services for what the fixed price covers, or tell us about your Slack workspace and we will scope it.
Questions
Can Mattermost import our Slack history?
Do private channels and direct messages come across?
Do Slack apps and workflows come across?
Do people keep their Slack passwords?
Is Mattermost open source?
How long does a Slack to Mattermost migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
