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.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

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
  1. 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.
  2. 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.
  3. 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:

  1. Channels, each with an owner. The daily files in each channel’s folder show when it was last used; archived channels import as archived.
  2. 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.
  3. Workflows built in Workflow Builder, with their triggers and owners.
  4. Webhook senders: monitoring, CI pipelines and scripts that post into Slack. Every one of their URLs changes.
  5. Guests and Slack Connect: single-channel and multi-channel guests, and channels shared with other organisations.
  6. 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.json moves 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-auth only 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

  1. Clients: Desktop and mobile apps are installed and pointed at the Mattermost server before the day, with sign-in tested on each.
  2. Integrations: Webhook senders and rebuilt workflows switch to Mattermost one by one, each checked on its first message.
  3. 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.
  4. Final import: A last export is converted and imported into the same team; posts already there are skipped.
  5. 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?

Yes. Mattermost converts a Slack export with its mmetl tool and loads it with mmctl. Users, public and private channels, direct and group messages, threads, reactions and file attachments come across with their original timestamps. What you get is bounded by the export your Slack plan allows, which is the first thing to check.

Do private channels and direct messages come across?

Only if they are in the export. On Free and Pro, the standard export covers public channels only, and Slack accepts an application for more only in limited cases, such as valid legal process or the consent of members. On Business+, a workspace owner applies for the export of all channels and conversations, which the Primary Owner approves and Slack reviews. On Enterprise, org owners request the export tools from Slack Support.

Do Slack apps and workflows come across?

No. Integrations are not part of a Slack export, so there is nothing to import. Incoming webhooks and custom slash commands that use Slack's format keep working once they point at a Mattermost URL. Slack apps, Block Kit messages and Workflow Builder workflows are rebuilt as Mattermost bots or n8n workflows.

Do people keep their Slack passwords?

No. Imported accounts get a generated password that nobody knows, and people set their own through Password Reset on the Mattermost login page. With single sign-on, which for an imported history means a paid Mattermost plan, they sign in with their directory account instead.

Is Mattermost open source?

The source is: the server under AGPL-3.0, and the compiled Team Edition that Mattermost builds under MIT. Mattermost positions Team Edition for teams under 250 activated users and has removed single sign-on from it. The free Entry edition has SAML and OpenID Connect sign-in but, according to Mattermost, shows only the most recent 10,000 messages. Sign-on with the full history, guest accounts, retention policies and compliance exports are in the paid plans that Mattermost licenses directly; we say in the proposal which one your requirements need.

How long does a Slack to Mattermost migration take?

It depends on three things: whether you need Slack to approve the full export, the size of the file archive, and the number of integrations to rebuild. Mattermost's own guide says an export under about 25 GB often imports within a day, while one over about 100 GB can take several days per run. Pilae quotes the move at a fixed price once the export and the inventory are in hand.

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.

Start with one workload

  • 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%.