Desktop App install guides

Available on all plans

Cloud and self-hosted deployments

The Mattermost desktop app is available for Linux, Mac, and Windows operating systems. The Desktop App supports all the features of the web experience, plus the following features:

• Connect to multiple Mattermost servers from a single interface, and navigate between servers using keyboard shortcuts.

• Auto-start Mattermost when a user logs into their machine.

• Add Mattermost to the Windows Start menu, the Taskbar, the Dock, or the System Tray.

• (Windows/macOS) Deep link to the desktop app via the mattermost:// protocol if the app is already installed.

• (Linux) Set up Desktop Entry for the application to more easily integrate into a desktop environment.

Install and update the Mattermost desktop app

You can download the desktop app directly from our Downloads page. You can also use the following installation guides for Linux, Mac, and Windows.

WindowsmacOSUbuntu/DebianCentOS/RHELGeneric Linux

Windows 8.1+ is required. Automatic app updates are supported and enabled. When a new version of the desktop app is released, your app updates automatically.

Install the Mattermost Desktop App

1. Download the latest version of the Mattermost desktop app: 32/64-bit version of Windows

2. From the Downloads folder, right-click on the file mattermost-desktop-setup-5.2.2-win.exe, then select Open to start an installer for the app. Once finished, the Mattermost desktop app opens automatically.

MSI Installer and group policies (beta)

You can download the latest version of the Mattermost desktop app MSI installer (Beta):

• MSI for 64-bit version of Windows

• MSI for 32-bit version of Windows

The following group policies are available:

Group policy	Description	Mattermost release	Setting	State options
Enable Server Management	If disabled, management of servers in the app settings are disabled.	v4.3 or later	EnableServerManagement	Not Configured Enabled Disabled
Default Server List	Define one or more default, permanent servers.	v4.3 or later	DefaultServerList
Automatic Updates	If disabled, automatic Desktop App updates are disabled.	v5.1 or later	EnableAutoUpdates

Disable automatic updates

Automatic desktop app updates can be disabled by configuring the supported group policy. See the MSI installer and group policy documentation for instructions on installing the Mattermost Desktop App via an MSI installer, and configuring supported group policies. Changes to group policies require you to restart Mattermost for those changes to take effect.

Log in using the desktop app

The first time you log in to Mattermost using the desktop app, you’ll see a splash screen that introduces you to desktop app functionality.

1. Select Get Started to connect to a Mattermost server.

2. Enter a Server URL and Server display name, then select Connect.

Tip

Can’t find your Mattermost server URL? Ask your company’s IT department or your Mattermost System Admin for your organization’s Mattermost Site URL. It’ll look something like https://example.com/company/mattermost, mattermost.yourcompanydomain.com, or chat.yourcompanydomain.com. These URLs could also end in .net.

Additional documentation resources

The following additional documentation resources are also available for the Mattermost desktop app:

• Desktop App changelog

• Minimum software requirements

• Configure your Desktop App experience

• Source code

• Contributor’s guide

Troubleshooting your Desktop App installation

Where is configuation stored locally?

The location of the Mattermost desktop app configuration file depends on the platform where you’re running Mattermost (and, in the case of macOS, how you’ve chosen to install the app):

• Windows: Users\<username>\AppData\Roaming\Mattermost

• macOS installer: /Users/<username>/Library/Application Support/Mattermost

• macOS App Store: /Users/<username>/Library/Containers/Mattermost/Data/Library/Application Support/Mattermost

• Linux: ~/.config/Mattermost

Note

• Local configuration data is not automatically removed when uninstalling the desktop app. If you wish to remove all data, you must manually remove the files from the applicable location noted above.

• Prior to uninstalling, you can choose to log out of any active sessions. You can terminate active sessions from another Mattermost session in Profile > Security > View and Logout of Active Sessions, then select Log Out. Desktop app sessions are labeled as Native Desktop App.

“Installation has failed” dialog

The app data might be corrupted. Remove all the files in %LOCALAPPDATA%\mattermost, then try reinstalling the app.

“The application “Mattermost” can’t be opened” dialog

On macOS Catalina, this dialog can be triggered if the Mac Archive Utility is the default method for decompressing files. In this case using a third-party tool such as Keka or Unarchiver may resolve the problem.

Desktop App window is black and doesn’t load the page

1. First, make sure you have installed the latest desktop app version.

2. Clear your cache and reload the app from View > Clear Cache and Reload or press Ctrl Shift R on Windows or Linux, or ⌘ ⇧ R on Mac.

3. Quit the app and restart it to see if the issue clears.

4. Disable GPU hardware acceleration from File > Settings on Windows and Linux or Mattermost > Settings on macOS, and unselect Use GPU hardware acceleration.

5. If you are using a special video driver, such as Optimus, try disabling it to see if the problem is resolved.

If none of the above steps resolve the issue, please open a new ticket in the Mattermost Troubleshooting Forum.

Desktop App is not visible, but the Mattermost icon is in the Task Bar

This issue can occur on Windows in a multiple-monitor setup. When you disconnect the monitor that Mattermost is displayed on, Mattermost continues to display at screen coordinates that no longer exist.

To resolve this issue, you can reset the desktop app screen location by deleting the screen location file. When the file is not present, the desktop app displays on the primary monitor by default.

To reset the desktop app screen location:

1. If the desktop app is running, right-click the Mattermost icon in the task bar, then select Close Window.

2. Open Windows File Explorer, and go to the %APPDATA%\\Mattermost folder.

3. Delete the file bounds-info.json.

Desktop App constantly refreshes the page

This issue can occur when localStorage has an unexpected state. To resolve the issue:

• Windows: Open Windows File Explorer, go to the %APPDATA%\Mattermost folder, then delete the Local Storage folder.

• Mac: Open Finder, go to the ~/Library/Application Support/Mattermost folder, then delete the Local Storage folder.

• Linux: Open the File Manager, go to the ~/.config/Mattermost folder, then delete the Local Storage folder. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using rm -rf ~/.config/Mattermost.

Desktop App constantly asks to log in to Mattermost server

This issue can occur after a crash or unexpected shutdown of the desktop app that causes the app data to be corrupted. To resolve the issue:

• Windows: Open Windows File Explorer, go to the %APPDATA%\\Mattermost folder, then delete the IndexedDB folder and the Cookies and Cookies-journal files.

• Mac: Open Finder, go to the ~/Library/Application Support/Mattermost folder, then delete the IndexedDB folder and the Cookies and Cookies-journal files.

• Linux: Open the file manager, go to the ~/.config/Mattermost folder, then delete the IndexedDB folder and the Cookies and Cookies-journal files. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using rm -rf ~/.config/Mattermost.

“Internal error: BrowserWindow ‘unresponsive’ event has been emitted”

Selecting Show Details on the dialog provides logs. Ways to resolve the issue:

1. Clear the cache via View > Clear Cache and Reload or press Ctrl Shift R on Windows or Linux, or ⌘ ⇧ R on Mac.

2. Go to App Settings via File > Settings (or by pressing Ctrl , on Windows or Linux, or ⌘ , on Mac) and unselect hardware acceleration.

Desktop app not responsive within Citrix Virtual Apps or Desktop Environment

Append Mattermost.exe; to the Registry Key HKLM\SYSTEM\CurrentControlSet\Services\CtxUvi\UviProcessExcludes and reboot the system.

For further assistance, review the Troubleshooting forum for previously reported errors, or join the Mattermost user community for troubleshooting help.

Report Desktop App issues

When reporting issues found in the Mattermost Desktop App, it’s helpful to include the contents of the Developer Tools Console along with the information on this page.

To access the Developer Tools Console:

1. In the menu bar, go to View > Developer Tools for Current Tab.

2. Select the Console tab.

3. Right-click the log entry, then select Save As.

4. Save the file, then send it along with a description of your issue.

5. Close the console to disable the Developer Tools.

You can open an additional set of developer tools for each server you have added to the desktop app. The tools can be opened by pasting this command in the Developer Tools Console you opened with the steps described above:

document.getElementsByTagName("webview")[0].openDevTools();

To submit an improvement or correction to this documentation, select Edit at the top of this page.