Slack to Mattermost Migration: A Step-by-Step Guide
Step-by-step guide to migrating from Slack to Mattermost. Export data, transform with mmetl, import with mmctl, and execute a smooth cutover. Plan your migration here.
- Slack to Mattermost migration requires Slack Business+ plan and takes 2-4 hours for 100 users, with technical work spread over one day of cutover.
- Use mmetl to transform your Slack export, then mmctl to import into Mattermost; both steps are reversible and safe to test beforehand.
- Messages, files, channels, and users transfer; Slack apps, custom emoji, and third-party integrations do not, so plan replacements before cutover.
- Email conflicts and timezone settings are the most common issues; audit users before export and test login on day one to catch problems early.
- You can keep Slack live during testing and run a final import before go-live, making rollback easy if something breaks.
Moving from Slack to Mattermost is doable. Your data stays with you, your team gets a fresh start, and your hosting bills drop. This guide walks you through export, transformation, import, and cutover in plain terms. Plan a weekend. Have a dry-run. Then go.
Before You Migrate: Planning & Prerequisites
Migration works when you plan it. You need Slack admin access, a Mattermost instance ready to receive data, and a team that knows this is coming. Start with three questions: which Slack workspace are you leaving, which users are moving, and when is cutover day? The process takes anywhere from a few hours (small teams) to a full day (500+ users), so schedule accordingly.
You will need Slack Business+ or higher plan to export data. Slack Free and Pro plans cannot export message history. If you are on Pro, this is actually a reason to migrate now: Slack charges $12.50 per user per month for Business+; Mattermost self-hosted costs nothing per user after you pay for hosting. Check your current Slack bill. Write down the number. You will reference it when justifying the switch to leadership.
Get your Mattermost environment ready first. You can use a fresh instance or an existing one. Fresh is cleaner. If you go fresh, make sure it is v9.0 or later; the mmetl tool (the transformation engine) works best on recent versions. You will also need access to the Mattermost server via SSH or the administrator console to run CLI commands later. Ask your hosting provider or your infrastructure team for that access now.
Last: read the limitations before you start. Slack Custom Emoji, Slack Connect channels, workflow automations, and some integrations do not transfer. Channels, direct messages, files, and user accounts do. We cover the full list later. Knowing what you are losing ahead of time prevents surprises at go-live.
Step 1: Export Your Data from Slack
Open Slack as an admin. Go to Administration > Workspace settings > Import/Export Data. Click Export. Slack will prepare a zip file with your entire workspace: channels, messages, files (up to the file size limits), reactions, user profiles, and metadata. This takes a few minutes for small workspaces, up to an hour for large ones.
Slack exports are strict on file size. Each file in the export can be no larger than 512 MB, and Slack compresses everything before packaging. If you have very large video or data files attached to messages, Slack may exclude them or warn you. Note which files (if any) did not make it into the export. You will need to re-upload those manually or migrate them separately after cutover.
Download the zip file. Do not unzip it yet. Verify the file size matches what Slack tells you it prepared. Store it somewhere safe on a machine where you have reliable internet; you will use it in the next step.
One tip: do your export during off-hours. Slack can throttle the export process if the workspace is under heavy load. A Thursday evening export is better than a Tuesday afternoon export.
Step 2: Prepare Your Mattermost Environment
You need a clean Mattermost workspace where you will import the data. If you are using Opsily's managed Mattermost hosting, create a new workspace or ask Opsily to provision a fresh instance for you. If you are self-hosting, spin up a Mattermost server and let it initialize.
Once Mattermost is live, log in as the admin. Create the teams that will exist after migration. In Mattermost, teams are containers; channels live inside teams. Slack does not have team concept, so you will map Slack channels to Mattermost teams. For example, all engineering-related Slack channels might live in an Engineering team in Mattermost, and all marketing channels in a Marketing team. Plan this mapping on paper first.
You can also create the teams after import and move channels around later, but doing it beforehand makes the import cleaner. Configure any other workspace-level settings now: authentication method (LDAP, SAML, etc.), email domain settings, file storage, and notification defaults.
Do not invite users yet. The import will create user accounts for everyone in the Slack export. If you pre-create user accounts manually, you will have duplicates. Let the import handle account creation.
Step 3: Transform the Export with mmetl
The mmetl tool (Mattermost Migration Export Tool) is a Python-based command-line utility that reads your Slack export zip and transforms it into Mattermost import format. You can run it on any machine with Python 3.8+; it does not need to run on the Mattermost server itself.
Install mmetl from GitHub or via pip:
pip install mmetl
Unzip your Slack export in a working directory. Run the mmetl command:
mmetl import-slack --slack-zip /path/to/slack-export.zip --output /path/to/output
The tool will read the Slack data, map channels and users, parse message history, and write the transformed data to a new directory. This directory contains jsonl files (one JSON object per line) that Mattermost understands.
If you want to test without actually importing, add the --validate flag first:
mmetl import-slack --slack-zip /path/to/slack-export.zip --validate
This does a dry-run and tells you if there are any format errors. Fix any warnings the validator reports. Common issues include user email conflicts (two Slack users with the same email domain, which is rare but happens) and missing channel names.
The transformation is fast: a 100 MB export typically takes seconds to a few minutes. Once done, you have a directory full of import files. Do not modify them by hand unless you know what you are doing.
Step 4: Import into Mattermost via mmctl
Now import the transformed data into your Mattermost workspace using mmctl, the Mattermost command-line control tool. You need access to the Mattermost server via SSH or terminal.
Connect to your Mattermost server and run:
mmctl import upload /path/to/mmetl/output
Then process the import:
mmctl import process <import-filename>
Mattermost will read the transformed files, create channels, user accounts, and message history. For a 500-user workspace with 10,000 messages, this takes 5-15 minutes. For larger workspaces, budget 30-60 minutes.
While the import runs, do not make changes in the Mattermost web interface. Resist the urge to peek at the channels. Let the process finish.
Once import completes, log into Mattermost and spot-check: do your channels exist, do you see message history, are user names correct? If something looks wrong, you can re-run the import process (it is idempotent, meaning it is safe to run twice). Delete channels and users in Mattermost first, then re-import.
What Transfers (and What Does Not)
Here is the honest list of what makes the move and what stays behind.
Transfers: All channels (including archived ones), all direct messages between users, message content and timestamps, file attachments (within size limits), user profiles and account names, message reactions and threads, channel topics and descriptions.
Does Not Transfer: Slack Connect channels (external shared channels), custom emoji (you can re-upload them, but it is manual), workflow automations and apps, user roles and permissions beyond basic admin/user status, message edits and deletion history (only the final state transfers), external integrations like Slack bots or third-party connectors.
Slack apps are the big one. If your team relies on Slack apps for notifications, CRM sync, or other workflows, you will need to set up Mattermost integrations or install Mattermost plugins on the other side. This is not automatic. Budget time for this before cutover.
File attachment limits matter if you stored large files in Slack. Mattermost's default max file size is 100 MB. If you have files larger than that, increase this limit in Mattermost's admin console before importing.
Common Migration Pitfalls & How to Avoid Them
Three things go wrong most often. Prepare for them.
First: email conflicts. If you have two users in Slack with the same email (rare, but possible in multi-workspace setups), the import will fail on the second one. Audit your Slack user list before export. Create a report of all users and their emails. If you find duplicates, deactivate the inactive account in Slack before export.
Second: timezone and timestamp confusion. Slack stores message timestamps in UTC. Mattermost displays them in the user's configured timezone. After import, your messages will show correct timestamps, but times in message search or API responses may look off if timezones are not configured consistently. Set a default timezone in Mattermost admin before import.
Third: user activation. When accounts are created via import, they default to email activation required. Users must verify their email address to log in. If you skip this step, users get stuck on the login screen. Before cutover day, send a welcome email to all users explaining that they need to check their email for a verification link. Better: if you are using LDAP or SAML, configure that before import so users authenticate directly without email verification.
Post-Migration: User Activation & Cutover
The technical migration is done. Now you need people to actually switch. This is the hard part.
Two days before cutover, send a memo: Slack is shutting down on [DATE] at [TIME]. Everyone logs in to Mattermost instead. Test it. Here is the URL. Here is how to reset your password. Do it now. Ask people to verify they can log in. Do not wait until cutover day to discover that someone's email is misconfigured.
On cutover day, do a final Slack export. Run the transformation and import again. This second import brings in any messages sent between your first import and cutover. It is safe to do; mmetl handles duplicate detection.
Shut down Slack. Turn off your Slack workspace, or at minimum, set a message on the workspace: "This workspace has moved to Mattermost. See your welcome email for login details." This prevents confusion. Some team members will try to use Slack out of muscle memory; a clear message redirects them fast.
Monitor Mattermost for the first 24 hours. Questions will come. Have an admin or ops person on standby. Typical issues: people forgetting passwords, confusion about teams and channels, missing integrations. Most resolve with a single email.
One bonus: do a short team meeting (30 min) on day one of Mattermost. Explain the channel structure, show people how to find old conversations, highlight any new Mattermost features they will like. Mattermost's interface is similar to Slack, but not identical. A quick walkthrough cuts support tickets in half.
Frequently Asked Questions
How long does a migration take? For a 100-user team with basic Slack usage, 2-4 hours of actual work spread over a day. The import itself takes 10-30 minutes. Most time is planning, testing, and getting people to log in.
Can I roll back if something goes wrong? Yes, easily. If the import has problems, delete the channels and imported users from Mattermost and re-import. You can also keep your Slack workspace live until you are certain everything in Mattermost is working, then do final cutover.
What happens to paid Slack features we used? Search history and archiving work in Mattermost out of the box. Slack Calls do not transfer; Mattermost has its own voice/video features. Slack Clips do not transfer; record and re-upload if needed. App integrations like Salesforce sync do not transfer; you will configure Mattermost equivalents.
Can I import multiple Slack workspaces into one Mattermost instance? Yes, but they will share channels and users. It is messy. Best practice: one Slack workspace = one Mattermost team. If you are consolidating multiple Slack workspaces, you have architectural decisions to make first.
Will users lose their direct message history? No. All DMs transfer. Users will see their entire conversation history with other team members in Mattermost.
Do we need downtime? Yes, one window. You need to export Slack, run the final import into Mattermost, and have everyone switch. This is typically 2-4 hours on a Friday or Saturday to minimize business impact. Plan accordingly with leadership.
What if someone is on vacation during cutover? Add them to Mattermost after they return, or have them log in remotely to activate their account. Accounts created during import are not deleted if users do not log in immediately.
The Bottom Line
Slack to Mattermost migration is a straightforward process if you follow the steps: export, transform, import, test, cutover. The biggest mistake is rushing it. Do a dry-run first. Test on a separate Mattermost instance. Get your team's buy-in before you announce the date.
One Slack user costs you money every month. One Mattermost user costs you nothing after the initial setup. If you are running a 50-person team, the math is clear. Read our guide to managed Mattermost hosting and see how you can have Opsily handle the infrastructure while you focus on the migration itself, or dive into our self-hosted Mattermost documentation and run it your way.