Category Archives: Guides

Upgrade to 3.0

Mattermost 3.0 lets users maintain a single account to use across multiple teams on a Mattermost server.

This means each user has one set of credentials, one place to configure all account settings, and a more streamlined sign-up and team joining process. This change also enables users to access all teams on a server using a single iOS or Android mobile applications.

Upgrading to Mattermost 3.0

For teams upgrading to 3.0 from 2.x:

  • This upgrade requires manual steps. Automation is not supported because you need to manually confirm that your database has been backed up before the database upgrade process can begin by typing “YES”, and you need to select a “default team” to preserve when managing duplicate accounts.
  • Users who created duplicate accounts across teams will need to take steps to unify accounts. Per the March 22, 2016 community announcement, Mattermost 3.0 will not support duplicate accounts.
    • Accounts with duplicate emails will have the local portion of their emails appended with their Team URL to make the emails unit (for example, if an account has a duplicate email on the /marketing team it will be renamed If users login using email and password,
    • Accounts with duplicate usernames will have usernames appended with their Team URL to make the usernames unique (for example, if an account has a duplicate username steve on the /marketing team it will be renamed marketing.steve)
  • Users should upgrade to new iOS and Android applications. Links will be posted after the Mattermost 3.0 release. After the upgrade, users will be able to switch among all teams under their Mattermost account for a given server. Note: Mattermost 3.0 mobile applications use the v3 API and won’t be backwards compatible with 2.x servers that use the v1 API. There will be a few days
  • Integrations using the Mattermost Web Service API will require upgrade. Per the community announcement on April 14, 2016, while integrations using the Golang or Javascript drivers should continue to function without changes, the underlying Mattermost Web Service API Version 1 is being replaced by the Mattermost Web Service API Version 3.

Notification to users with duplicate accounts

As part of the upgrade to Mattermost 3.0, users with duplicate accounts will receive an email similar to the following:

[MATTERMOST] Changes to your account for Mattermost 3.0 Upgrade



Your Mattermost server is being upgraded to Version 3.0, which lets you use a single account across multiple teams.

You are receiving this email because the upgrade process has detected your account had the same email or username as other accounts on the server.

The following updates have been made: 

- The duplicate email of an account on the `/design` team was changed to ``. If you use email and password to login, you can use this new email address for login.
- The duplicate username of an account on the team site `/marketing` has been changed to `` to avoid confusion with other accounts.

As a result of these updates, your account on the team site `/developers` now has a unique email address and username and is considered your "primary" account. 

It is recommended that you login to your teams used by your duplicate accounts and add your primary account to the team and any public channels and private groups which you wish to continue using. 

This gives your primary account access to all public channel and private group history. You can continue to access the direct message history of your duplicate accounts by logging in with their credentials. 


To import your theme from a duplicate account, follow these instructions:


For more information on the upgrade to Mattermost 3.0 please see:

Importing Theme Colors

Please see online instructions for exporting a theme from a duplicate account. Then see online instructions for importing a theme to your primary account. The ability to use different themes per team will be added to a future release.

Case Study

A week after Mattermost 3.0 was released a deployment with over 3000 users and 200 teams underwent the migration smoothly, with fewer than 0.6% of accounts needing help.