Desktop App install guides
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.
A .deb
package is available for Debian 9 and for Ubuntu releases 18.04 LTS or later. Automatic app updates aren’t supported. You must update your app manually.
At the command line, set up the Mattermost repository on your system:
curl -o- https://deb.packages.mattermost.com/setup-repo.sh | sudo bash
Install the Mattermost Desktop App:
sudo apt install mattermost-desktop
Update the Mattermost Desktop App:
sudo apt upgrade mattermost-desktop
Snapcraft package
A snap is available for systems that have Snapcraft installed. Snapcraft is installed by default on Ubuntu 16.04 and later, but for most other Linux distributions you can install it manually. To install Snapcraft, see Install snapd on the Snapcraft website for details.
At the command line, execute the following command:
sudo snap install mattermost-desktop --beta
Run Mattermost as a desktop app.
Tip
You can review the current version of your Desktop App by selecting the More icon located in the top left corner of the Mattermost window, then selecting Help > Version….
Beta .rpm
packages are available for CentOS and RHEL 7 and 8. Automatic app updates aren’t supported. You must update your app manually.
Install the Mattermost Desktop App
Download the latest version of the Mattermost Desktop App:
64-bit systems mattermost-desktop-5.1.0-linux-x86_64.rpm
32-bit systems mattermost-desktop-5.1.0-linux-i686.rpm
At the command line, execute one of the following commands based on the package you downloaded:
64-bit systems:
sudo rpm -i mattermost-desktop-5.1.0-linux-x86_64.rpm32-bit systems:
sudo rpm -i mattermost-desktop-5.1.0-linux-i686.rpm
Run Mattermost as a desktop app.
Manually update the Desktop App
64-bit systems:
sudo rpm -u mattermost-desktop-5.1.0-linux-x86_64.rpm
32-bit systems:
sudo rpm -u mattermost-desktop-5.1.0-linux-i686.rpm
Tip
You can review the current version of your Desktop App by selecting the More icon located in the top left corner of the Mattermost window, then selecting Help > Version….
A beta AppImage distribution of a compressed tarball is available. Automatic app updates aren’t supported. You must update your app manually.
Download the latest version of the Mattermost Desktop App:
64-bit systems: mattermost-desktop-5.1.0-linux-x64.tar.gz
32-bit systems: mattermost-desktop-5.1.0-linux-ia32.tar.gz
Extract the archive to a convenient location, then execute
mattermost-desktop
located inside the extracted directory.To create a Desktop launcher, open the file
README.md
, and follow the instructions in the Desktop launcher section.
MacOS 10.15+ is required. You have two ways to install the Desktop App, and how you install the app determines whether it updates automatically.
Install from the App Store
We recommend that you install the Desktop App from the App Store. When you install through the App Store, your Desktop App updates automatically when a new release is available.
Download the Desktop App from GitHub
You can download the Desktop App directly from our GitHub release page. However, when you install the Desktop App this way, you can’t manually check for updates, and updates won’t be installed automatically.
Download the latest version of the Mattermost desktop app:
M1 systems (Beta)
Double-click the download to open the disk image.
Drag the Mattermost application to the Applications folder.
Tip
You can review the current version of your Desktop App by selecting Mattermost > About Mattermost from the macOS menu bar.
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
Download the latest version of the Mattermost desktop app: 32/64-bit version of Windows
From the Downloads folder, right-click on the file
mattermost-desktop-setup-5.1.0-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 |
|
|
Default Server List |
Define one or more default, permanent servers. |
v4.3 or later |
|
|
Automatic Updates |
If disabled, automatic Desktop App updates are disabled. |
v5.1 or later |
|
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.
Additional documentation resources
The following additional documentation resources are also available for the Mattermost Desktop App:
Troubleshooting your Desktop App installation
“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
First, make sure you have installed the latest desktop app version.
Clear your cache and reload the app from View > Clear Cache and Reload or use CTRL/CMD+SHIFT+R.
Quit the app and restart it to see if the issue clears.
Disable GPU hardware acceleration from File > Settings on Windows and Linux or Mattermost > Settings on macOS, and unselect Use GPU hardware acceleration.
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:
If the desktop app is running, right-click the Mattermost icon in the task bar, then select Close Window.
Open Windows File Explorer, and go to the
%APPDATA%\\Mattermost
folder.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 theLocal Storage
folder.Mac: Open Finder, go to the
~/Library/Application Support/Mattermost
folder, then delete theLocal Storage
folder.Linux: Open the File Manager, go to the
~/.config/Mattermost
folder, then delete theLocal Storage
folder. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal usingrm -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 theIndexedDB
folder and theCookies
andCookies-journal
files.Mac: Open Finder, go to the
~/Library/Application Support/Mattermost
folder, then delete theIndexedDB
folder and theCookies
andCookies-journal
files.Linux: Open the file manager, go to the
~/.config/Mattermost
folder, then delete theIndexedDB
folder and theCookies
andCookies-journal
files. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal usingrm -rf ~/.config/Mattermost
.
“Internal error: BrowserWindow ‘unresponsive’ event has been emitted”
Selecting Show Details on the dialog provides logs. Ways to resolve the issue:
Clear the cache via View > Clear Cache and Reload or CTRL+SHIFT+R.
Go to App Settings via File > Settings or CTRL+COMMA 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:
In the menu bar, go to View > Developer Tools for Current Tab.
Select the Console tab.
Right-click the log entry, then select Save As.
Save the file, then send it along with a description of your issue.
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();