Python Mattermost Driver

7.3.2 · active · verified Fri Apr 17

Mattermostdriver is a Python library providing a client for the Mattermost API. It enables developers to interact with Mattermost servers, manage users, channels, posts, and more. The current version is 7.3.2, and it maintains an active release cadence with regular updates and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'mattermostdriver'
```
cause The `mattermostdriver` package is not installed in your current Python environment.

fix Run `pip install mattermostdriver` to install the library.
```
Login failed in version 6.3.0
```
cause Specific bug in mattermostdriver version 6.3.0 prevented successful user login for some configurations.

fix Upgrade to `mattermostdriver>=7.3.2` to resolve known login issues. If upgrading is not possible, review your Mattermost server's authentication settings and driver configuration carefully.
```
websocket._exceptions.WebSocketConnectionClosedException: WebSocket connection is already closed.
```
cause Attempting to send or receive data over a WebSocket connection that has already been closed or was never properly established.

fix Ensure `driver.init_websocket()` and `driver.login()` are successful before attempting WebSocket operations. Check network connectivity and Mattermost server WebSocket settings. Upgrade to `mattermostdriver>=7.3.1` for disconnect fixes.
```
requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))
```
cause The Mattermost server unexpectedly closed the connection, often due to incorrect server URL/port, invalid SSL certificate, or firewall issues.

fix Verify that the `url`, `port`, and `scheme` in your `Driver` configuration are correct and reachable. If using `https`, ensure `verify` is set correctly for your server's SSL certificate, or temporarily set `verify: False` for testing (not recommended for production).

Warnings

breaking Python 3.4 support was dropped in version 7.0.0. Projects still on Python 3.4 will need to upgrade their Python version to 3.5 or newer to use mattermostdriver 7.x.x and above.
Fix: Upgrade your Python environment to version 3.5 or higher. Alternatively, pin your mattermostdriver dependency to `<7.0.0` if you cannot upgrade Python.
gotcha Inconsistent authentication behavior and login failures were reported in versions leading up to 7.3.2, specifically in 6.3.0. This could manifest as unexpected login failures or issues with session persistence.
Fix: Upgrade to mattermostdriver version 7.3.2 or later to benefit from the fixes related to authentication stability.
gotcha Issues with WebSocket disconnects not functioning correctly were present in versions prior to 7.3.1. This could lead to orphaned or persistent WebSocket connections.
Fix: Upgrade to mattermostdriver version 7.3.1 or later to ensure reliable WebSocket disconnection.
gotcha Major dependency versions (e.g., `websockets`, `requests`) have been bumped in recent releases (e.g., 7.2.0, 7.3.1). This might introduce dependency conflicts if your project relies on older versions of these libraries for other components.
Fix: Carefully manage your project's dependency tree. Consider using `pip install --no-deps` for mattermostdriver and manually installing compatible versions of `requests` and `websockets` if conflicts arise. Using virtual environments for each project is highly recommended.

Install

pip install mattermostdriver Install stable version

Imports

Driver
```
from mattermostdriver import Driver
```

Quickstart

This quickstart demonstrates how to initialize the `Driver`, log in using username/password (or token if provided via environment variable `MATTERMOST_TOKEN`), retrieve the current user's information, and then log out. Ensure your Mattermost server details and credentials are set as environment variables or passed directly to the Driver constructor.

import os
from mattermostdriver import Driver

# Configure driver with environment variables or provide directly
driver = Driver({
    'url': os.environ.get('MATTERMOST_HOST', 'localhost'),
    'login_id': os.environ.get('MATTERMOST_LOGIN_ID', 'user@example.com'),
    'password': os.environ.get('MATTERMOST_PASSWORD', 'yourpassword'),
    'scheme': os.environ.get('MATTERMOST_SCHEME', 'https'),
    'port': int(os.environ.get('MATTERMOST_PORT', 443)),
    'verify': os.environ.get('MATTERMOST_VERIFY_SSL', 'true').lower() == 'true',
    'token': os.environ.get('MATTERMOST_TOKEN', '') # Optional: for token-based auth
})

try:
    driver.login()
    current_user = driver.users.get_current_user()
    print(f"Successfully logged in as: {current_user['username']} (ID: {current_user['id']})")
    # Example: Get system info
    # info = driver.system.get_ping()
    # print(f"Mattermost Server Status: {info}")

except Exception as e:
    print(f"Login failed: {e}")
finally:
    if driver.is_connected():
        driver.logout()
        print("Logged out.")

view raw JSON →