Migrate Slack History to Mattermost (Open Source Chat)

Hey team, Darian here. A few quarters back, I was digging through old Slack archives trying to find a critical decision made about our CI/CD pipeline. It took hours. That’s when we decided to centralize our chat history in our self-hosted Mattermost instance. The ability to own our data and have a single, powerful, searchable archive has been a game-changer. This migration process, once automated, saved my team from that exact headache, and I want to show you how to set it up.

This isn’t just about ticking a compliance box; it’s about making your team’s collective knowledge accessible for the long haul. Let’s get it done.

Prerequisites

Before we dive in, make sure you have the following ready. This will make the whole process much smoother.

• Slack Admin Access: You’ll need permissions to export your workspace history.
• Mattermost System Admin Access: Required to run the command-line tools and import the data.
• A Linux/macOS Machine: This is where you’ll run the transformation script. A local machine works fine for smaller exports.
• Python 3.8+ installed: The transformation tool we’ll use is a Python package.
• Mattermost Command Line Tool (mmctl): You’ll need this installed and configured to talk to your Mattermost server.

The Guide: Step-by-Step

Step 1: Export Your Slack History

First things first, we need the data from Slack. Slack provides a standard export feature that bundles all public channel messages, user data, and channel information into a ZIP file.

1. Navigate to your-workspace.slack.com/services/export.
2. Choose a date range for the export. For a full migration, you’ll want to select the entire history.
3. Start the export. Slack will email you a link to download the ZIP file when it’s ready. This can take a while for large workspaces.
4. Once you have the file, download it and unzip it into your project directory.

Pro Tip: The standard Slack export does not include private channels or direct messages. Migrating that data requires their Corporate Export plan, which is a different process. For today, we’re focusing on the standard, public history.

Step 2: Prepare Your Environment and Tools

Alright, let’s get our workspace ready. I’m going to skip the standard virtualenv setup since you likely have your own workflow for that. The key is to have a clean project directory where you’ve unzipped your Slack export.

The magic ingredient for this migration is the mattermost-bulk-load-tool, or `mmetl`. It’s a Python library that handles the heavy lifting of converting Slack’s export format into something Mattermost can understand. You’ll want to grab that from PyPI using your preferred Python package manager.

Step 3: The Transformation Script

Now for the core logic. We’ll write a simple Python script to orchestrate the `mmetl` tool. Create a new file, let’s call it `transform_slack.py`.

The script’s job is to:

1. Define the Mattermost team we’re importing into.
2. Point the transformer at our unzipped Slack export directory.
3. Run the transformation and generate a single mattermost_import.jsonl file.

Here’s the script I use. It’s lean and gets the job done.

import logging
from mmetl.main import etl_custom

# Basic logging setup
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

# Configuration
# The name of the team in Mattermost you want to import the history into.
# This team MUST already exist in your Mattermost instance.
MATTERMOST_TEAM_NAME = 'tech-operations'

# The path to your unzipped Slack export directory.
SLACK_EXPORT_PATH = './slack_export'

# The name of the output file Mattermost will use.
OUTPUT_FILE_PATH = './mattermost_import.jsonl'


def run_migration():
    """
    Orchestrates the Slack to Mattermost ETL process.
    """
    logging.info(f"Starting Slack to Mattermost transformation for team: {MATTERMOST_TEAM_NAME}")
    logging.info(f"Reading from: {SLACK_EXPORT_PATH}")

    try:
        # This is the core function from the mmetl library
        etl_custom(
            'slack',  # Specify the source platform
            team_name=MATTERMOST_TEAM_NAME,
            skip_users=False,
            start_time=None,  # None means process all messages
            slack_export_path=SLACK_EXPORT_PATH,
            output_path=OUTPUT_FILE_PATH,
            force=True  # Overwrite the output file if it exists
        )
        logging.info(f"Successfully created Mattermost import file: {OUTPUT_FILE_PATH}")
    except Exception as e:
        logging.error(f"An error occurred during transformation: {e}")
        # In a real script, you might want to clean up partial files here.
        return

if __name__ == '__main__':
    run_migration()

Pro Tip: Make sure the `MATTERMOST_TEAM_NAME` exactly matches the team “handle” or URL name in Mattermost (e.g., ‘tech-operations’ from `your-mattermost.com/tech-operations`). A mismatch here is a common failure point.

Step 4: Generate the Mattermost Import File

With the script in place, running the transformation is simple. Open your terminal in the project directory and execute the script. You’ll need to use your python interpreter, which might be `python3` or just `python` depending on your system setup.

After it completes, you’ll find a new file named mattermost_import.jsonl in your directory. This file contains all your users, channels, and messages formatted for the Mattermost bulk importer.

Step 5: Import into Mattermost

We’re on the home stretch. Now we use `mmctl` to push this data into our Mattermost instance. This is a two-step process: first upload the file, then tell Mattermost to process it.

Make sure your `mmctl` is authenticated with your Mattermost server first.

1. Upload the import file:
   
   `mmctl import upload ./mattermost_import.jsonl`
   
   This command will upload the file to your Mattermost server and return an import ID. Copy this ID!
2. Process the file:
   
   `mmctl import process –workers 4 <IMPORT_ID>_mattermost_import.jsonl`
   
   Replace `` with the ID you copied. The `–workers` flag can speed things up on larger imports. I find 4 is a safe number for most setups.
3. Check the status:
   
   `mmctl import job show <JOB_ID>`
   
   The `process` command will give you a job ID. You can use this to monitor the import’s progress. It will show you if there are any errors.

Common Pitfalls (Where I Usually Mess Up)

I’ve run this process dozens of times, and here are the traps I’ve fallen into so you don’t have to:

• User Email Mismatch: The import process matches Slack users to Mattermost users based on their email address. If a user’s email is different between the two platforms, their messages will be imported but attributed to a guest or placeholder account. It’s worth running a quick check before you start.
• Import File Size Limit: By default, Mattermost has a file size limit for uploads (often around 100MB). For massive Slack histories, your `jsonl` file might exceed this. You may need to temporarily increase the `MaxFileSize` setting in your Mattermost `config.json` file and restart the server before uploading.
• Forgetting to Create the Team: The script assumes the destination team already exists in Mattermost. If it doesn’t, the import will fail immediately. Double-check that `MATTERMOST_TEAM_NAME` is correct and the team is set up.

Conclusion

And that’s the core workflow. A little bit of prep, one Python script, and a few command-line calls are all it takes to move years of valuable conversation history into a platform you fully control. This process puts your data back in your hands, making it a permanent, searchable asset for your entire organization. Happy migrating!

— Darian Vance

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions