How to Upgrade Mattermost: A Step-by-Step Guide

Upgrading your Mattermost server keeps you secure, gives you new features, and ensures database compatibility with your infrastructure. But done wrong, it can cost you hours of downtime and data loss. This guide walks you through the entire process: version planning, pre-flight safety checks, backup procedures, both binary and Docker upgrades, verification, and recovery if something fails.

When Should You Upgrade Mattermost?

You upgrade Mattermost for three reasons: security patches, feature access, and end-of-life dates. Every release fixes vulnerabilities. If you are running v10 or earlier, you are missing security improvements in v11. Mattermost publishes new features every month in regular releases, but holds them back for larger organizations through Extended Support Releases (ESR). The current ESR version is v10.11, which reaches end-of-life on August 15, 2026. After that date, no security patches are available, even if you pay for enterprise. Running unsupported versions exposes you to known vulnerabilities that competitors' security audits will flag.

For small teams, monthly releases (v11.11.3 is the latest as of November 2026) offer more features faster. For large enterprises, ESR versions provide 12 months of stability and patches without feature changes. Your upgrade timing depends on which track you chose when you installed Mattermost, not on which is "newer."

Schedule upgrades quarterly or when security advisories drop. Check the official release notes before committing to a date. Some releases change your database schema, requiring downtime. Others are file-only and can run in seconds if you have read replicas.

What's the Difference Between ESR and Regular Releases?

Mattermost publishes two release tracks. Regular releases come every month and include new features, UI changes, API improvements, and bug fixes. Extended Support Releases (ESR) come four times per year and lock in a feature set for 12 months. ESR versions are named v9, v10, v11 and receive only security and stability patches, never new features. Regular versions are named v9.1, v9.2, v10.1, v11.11.3, etc.

If you run regular releases, you must upgrade monthly to stay current. Most teams upgrade quarterly instead and tolerate a gap in coverage. If you run ESR, you upgrade only when a critical security issue is announced, typically two to four times per year. ESR versions get 12 months of support from release date. v10.11, released in August 2025, ends support on August 15, 2026. On that date, you must migrate to v11 ESR or regular releases, or run unsupported code.

Your upgrade path depends on which track you are on. ESR to ESR upgrades (v9 ESR to v10 ESR) require backing up, extracting files, and restarting. Regular to regular (v11.10 to v11.11) is the same procedure. Cross-track upgrades (v10 ESR to v11.1 regular, or v10.1 regular to v10.11 ESR) are supported but reset your upgrade schedule. If you run v10.1 (regular) today and upgrade to v10.11 (ESR), you now get 12 months of support from today, not from August 2025.

Preparing Your Server for Upgrade: Pre-Flight Checklist

Before you touch anything, verify four facts: your current version, your installation method, disk space, and database type. Log into the System Console (Admin menu > System Console) and find the current version under About. It shows v10.11 or v11.11.3 or similar. If you do not have admin access, ask your administrator or check /system_console on your domain.

Next, find your installation method. SSH into your server and run which mattermost. If it returns a path like /opt/mattermost/bin/mattermost, you are running binary. If your Mattermost is in a Docker container, you are running Docker. If you see neither, you are running a managed service (Opsily, Mattermost Cloud, etc.) and upgrades are automatic or handled by your provider.

Check your disk space. You need at least 2x your database size, plus 500 MB for the new Mattermost binary. Run du -sh /var/lib/postgresql (or /var/lib/mysql if using MySQL) to see database size. Run df -h / to see available disk. If free space is less than 2x database size, clean up old data or add storage before proceeding.

Note your database type. PostgreSQL or MySQL. If you run MySQL, you must migrate to PostgreSQL before upgrading to Mattermost v10 or later. MySQL support ended in v9. If you run v9 on MySQL, upgrade to v9.x on MySQL first, back up everything, then migrate to PostgreSQL before jumping to v10.

Decide your downtime window. Upgrades typically take 5-30 minutes depending on database size and plugin count. Notify your team. For high-availability clusters (multiple Mattermost servers), apply the upgrade to one node, verify, then roll out to others. For single servers, schedule a 1-hour window.

How to Backup Your Mattermost Database and Files

Back up before every upgrade, even for patch releases. You need two backups: the database and the files (config, plugins, user data). If anything fails, you restore both together.

For PostgreSQL, run this command on your database server:

pg_dump -U mattermost mattermost > mattermost-backup.sql

This dumps the Mattermost database to a file. It takes 10 seconds to minutes depending on size. Replace mattermost with your actual database name if different.

For MySQL, run:

mysqldump -u mattermost -p mattermost > mattermost-backup.sql

You will be prompted for the password. Both commands create a text file you can restore later.

Next, back up the files. Stop your Mattermost server first (see the upgrade procedure below for systemctl commands). Then copy the entire Mattermost directory:

cp -r /opt/mattermost /backup/mattermost-backup-$(date +%Y%m%d)

This preserves config files, plugins, custom themes, and logs. If you run Docker, back up your docker-compose.yml file and any volumes:

docker cp mattermost:/mattermost /backup/mattermost-backup-$(date +%Y%m%d)

Test your restore before relying on it. Restore the SQL file to a test database and verify you can log in:

psql -U mattermost < mattermost-backup.sql

If restore succeeds without errors, your backup is valid. Move backup files to a separate server or cloud storage. Do not leave them on the Mattermost server.

Upgrading via Binary or Tarball: Step-by-Step

Binary upgrades are the most common for self-hosted servers on Linux. You download the new Mattermost release, extract it, and restart.

1. Download the new version. Visit https://mattermost.com/download to find download links for each release version. Select the Linux tarball (not the source code) for your target version.

2. Stop the Mattermost server. If you run systemd:

sudo systemctl stop mattermost

If you run init.d:

sudo /etc/init.d/mattermost stop

Wait 5 seconds to ensure the process stops.

3. Back up your current installation. We did this in the previous section, but do it again now:

cp -r /opt/mattermost /backup/mattermost-backup-preupgrade-$(date +%Y%m%d)

If upgrade fails, you restore this backup and restart.

4. Extract the new version and preserve your config. Extract the tarball to a temporary directory:

tar -xzf mattermost.tar.gz -C /tmp

Copy the new binary files into place, but preserve your old config file:

cp /opt/mattermost/config/config.json /tmp/config-backup.json
sudo rm -rf /opt/mattermost
sudo mv /tmp/mattermost /opt/mattermost
sudo cp /tmp/config-backup.json /opt/mattermost/config/config.json

Do NOT skip the config backup. Your config contains database connection strings, SMTP settings, and plugin configurations. Losing it means reconfiguring everything.

5. Fix file ownership and capabilities. The new files are owned by your user. Mattermost expects them owned by the mattermost user:

sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod u+rw /opt/mattermost/config/config.json

If you use socket activation on Linux, also set the capabilities flag:

sudo setcap cap_net_bind_service=+ep /opt/mattermost/bin/mattermost

This allows Mattermost to bind to port 80 or 443 without running as root.

6. Start the server. Run:

sudo systemctl start mattermost

Wait 10 seconds for the database migrations to complete. Your first startup after an upgrade runs schema updates; this can take a few minutes if your database is large.

7. Verify the upgrade. See the verification section below.

Upgrading via Docker: Step-by-Step

Docker upgrades are simpler if you use official docker-compose files. The process is: stop, update the image tag, pull, and restart.

1. Prepare your docker-compose.yml file. If you are using mattermost-docker (the deprecated community repo), migrate to the official Mattermost images first. The old repo is no longer maintained. Find your docker-compose.yml and locate the MATTERMOST_IMAGE_TAG or image: line.

2. Update the image tag. Change:

image: mattermost/mattermost:11.10.0

to:

image: mattermost/mattermost:11.11.3

Or, if using environment variables:

MATTERMOST_IMAGE_TAG=11.11.3

3. Back up your volumes. Docker stores your database and files in volumes. Before pulling a new image, snapshot them. If you use named volumes, run:

docker run --rm -v mattermost_data:/data -v /backup:/backup ubuntu tar czf /backup/mattermost-data-backup.tar.gz -C /data.

This backs up the data volume to /backup/mattermost-data-backup.tar.gz on the host.

4. Bring the deployment down, pull, and bring it up. Run:

docker-compose down
docker-compose pull
docker-compose up -d

The pull command fetches the new image. The up -d command starts the container. Docker mounts your existing volumes, so config and data persist.

5. Verify the upgrade. See the verification section below.

Common Docker trap: using generic tags like mattermost:latest or mattermost:release-x.x instead of exact versions like mattermost:11.11.3. Generic tags point to the latest build, and docker pull fetches the newest version. If your docker-compose.yml uses latest and you run docker-compose pull, it silently downgrades you if a build system publishes an older tag. Always use explicit version numbers in production.

Verifying Your Upgrade Worked

After startup, verify the upgrade succeeded before declaring victory. Three checks confirm success.

1. Check the logs. For binary deployments:

sudo journalctl -u mattermost -n 50 | grep -i error

If you see errors, read them carefully. Common errors: "cannot bind to port" (another process owns port 80/443), "database connection failed" (config.json has the wrong connection string), or "plugin failed to load" (incompatible plugin version). For Docker:

docker-compose logs mattermost | grep -i error

2. Log into the web interface. Open your Mattermost URL in a browser and log in as an admin. Go to System Console > About. The version should now show v11.11.3 (or your target version). If it still shows the old version, the upgrade failed or you are looking at an old server instance.

3. Check critical features. Send a test message in a public channel. Upload a file. Edit a user. If all these work without errors, you are live. Database migrations run automatically on startup; you do not need to run them manually.

What to Do If Your Upgrade Fails: Rollback and Recovery

Failures happen. Most are reversible if you followed the backup steps above.

If Mattermost fails to start or errors appear in logs, roll back immediately. Do not troubleshoot on the production server.

1. Stop the current (broken) instance. Run:

sudo systemctl stop mattermost

2. Restore your backup. For binary, restore the files and database:

sudo rm -rf /opt/mattermost
sudo cp -r /backup/mattermost-backup-preupgrade-$(date +%Y%m%d) /opt/mattermost
sudo chown -R mattermost:mattermost /opt/mattermost
psql -U mattermost < /backup/mattermost-backup.sql

For Docker:

docker-compose down
docker-compose pull  # pulls the OLD tag from docker-compose.yml, revert it first
docker-compose up -d

Wait 30 seconds for the database to restore.

3. Start the server and verify.

sudo systemctl start mattermost

Common upgrade failures:

• "database schema mismatch" error: Your backup restore did not complete. Restore again and wait longer (5-10 minutes for large databases).
• "plugin xyz failed to load" error: The plugin is incompatible with the new version. Disable it in System Console > Integrations > Plugins, then restart. Ask the plugin vendor for a compatible version, or contribute a fix on GitHub.
• "cannot open database connection" error: Your config.json connection string is wrong. Check it matches your database host, port, and credentials. After fixing it, restart.
• File permission errors (permission denied): You forgot to run chown after extracting the new binary. Do it now and restart.

If rollback fails, restore from the database backup to a test server and check logs there. Most issues are configuration-related, not data loss. If you suspect data corruption, contact Mattermost support or your hosting provider.

Frequently Asked Questions

What's the difference between ESR and regular releases?

Regular releases publish every month and include new features, UI changes, and bug fixes. ESR (Extended Support Release) versions publish every quarter and include only security patches and bug fixes, no new features. ESR versions get 12 months of support; regular versions get one month. Choose ESR if you want stability; choose regular if you want the latest features.

Can I skip major versions during upgrade?

You cannot skip major versions (v9 to v11 directly is not supported). You must upgrade through intermediate versions: v9 to v10, then v10 to v11. Within a major version (v11.10 to v11.11), you can skip minor releases. The upgrade path is enforced by database schema validation.

How do I backup my Mattermost server before upgrading?

Back up two things: the database and the files. For PostgreSQL, run pg_dump -U mattermost mattermost > backup.sql. For files, run cp -r /opt/mattermost /backup/ (binary) or docker cp mattermost:/mattermost /backup/ (Docker). Store backups on a separate server or cloud storage.

What should I do if the upgrade fails?

If Mattermost fails to start or errors appear, stop the service, restore your backup, and restart. Use systemctl or docker-compose down to stop cleanly. If restore fails, restore to a test server and check logs. Most failures are config-related, not data loss.

Do I need to manually migrate from MySQL to PostgreSQL?

Yes, before upgrading to Mattermost v10 or later. MySQL support ended in v9. Mattermost provides migration tools on their documentation site. Back up your MySQL database, set up PostgreSQL, run the migration tool, test, then upgrade to v10. Do not skip this step.

How long does a typical upgrade take?

Binary and Docker upgrades finish in 5-30 minutes depending on database size. Backup and restore add 5-10 minutes each. Plan for a 1-hour maintenance window. Very large databases (100 GB+) may need 30-60 minutes for schema migration.

Can I upgrade without downtime?

Yes, if you run a Mattermost cluster with multiple servers behind a load balancer. Upgrade one node at a time, take it out of the load balancer rotation, verify it, and return it. Clients reconnect to other nodes. This requires Mattermost Professional or Enterprise license and careful orchestration. For single-server deployments, you must take downtime.

The Bottom Line

Upgrading Mattermost is straightforward if you back up first, verify your environment, and follow the step-by-step process. Security patches matter; running v10.11 after August 15, 2026, leaves you exposed to known vulnerabilities. Plan upgrades quarterly, test backups once, and you will be fine. If you run a large team or need zero-downtime upgrades, switch to managed hosting where upgrades are handled for you. Check our Mattermost hosting guide for hosted options.