How to Set Up a Matrix Bot with Python and Simple-Matrix-Bot-Lib

What are you actually choosing when you build a Matrix bot this way?

Simple-Matrix-Bot-Lib is a convenience layer on top of the Python matrix-nio client library. That makes it attractive when you want a small command bot, notification bot, or room helper without writing the full Matrix sync and event-handling loop yourself. The trade-off is that you accept the abstractions and authentication patterns exposed by the wrapper instead of controlling every Matrix client detail directly.

As of October 6, 2026, PyPI lists simplematrixbotlib 2.13.1, released March 29, 2026, and requiring Python 3.9 or newer but earlier than Python 4. The project's Read the Docs site currently warns that its documentation is unmaintained and may be out of date, so this guide uses PyPI and the current Matrix specification as the primary references and treats older documentation as implementation guidance rather than proof of current behavior.

For the package itself, see the simplematrixbotlib project on PyPI. For protocol behavior, use the current Matrix Client-Server API specification.

Simple-Matrix-Bot-Lib, matrix-nio, or an Application Service?

If your goal is “reply to commands in rooms as one bot account,” Simple-Matrix-Bot-Lib is usually the shortest path. If you already know you need custom authentication, unusual sync behavior, detailed device verification, or low-level encryption control, starting with matrix-nio can avoid fighting a wrapper later. For bridges or integrations that need homeserver-level routing, read the Matrix Application Service API instead of treating a normal bot account as a substitute.

Step 1: Choose a homeserver and confirm how the bot can log in

A Matrix bot needs a Matrix user account on a homeserver. You can use a public homeserver that permits account creation or an account on a homeserver you administer. Keep the bot separate from your personal Matrix identity so permissions, room membership, and credentials can be managed independently.

The important decision is authentication. The current Matrix specification supports both the legacy authentication API and OAuth 2.0. A homeserver may expose one or both. Simple-Matrix-Bot-Lib's published quick-start examples use a homeserver URL, username, and password, so this tutorial assumes your server still offers a compatible password login flow.

Before writing code, check the login methods exposed by your homeserver:

curl https://matrix.example.com/_matrix/client/v3/login

If the response includes a password login flow, the credential-based example below is a reasonable fit. If the server is SSO-only or OAuth-only, do not force a password into the example. In that situation, confirm the authentication support in the current library release or use a lower-level client that supports the flow you need. The Matrix specification explains login discovery and token handling in the login section of the Client-Server API.

Step 2: Create an isolated Python environment and install the library

Use a virtual environment so the bot's dependencies are separated from system Python and from unrelated projects. The current PyPI metadata requires Python 3.9 or later.

mkdir matrix-bot
cd matrix-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install simplematrixbotlib

On Windows PowerShell, activate the environment with:

.venv\Scripts\Activate.ps1

Verify what was installed rather than assuming a version from an old tutorial:

python -m pip show simplematrixbotlib

That version check matters because the public Read the Docs pages still show older documentation and explicitly warn that they may be outdated. If an example from those pages conflicts with the installed package, inspect the release metadata and current repository before changing your code to match the older page.

Do you need end-to-end encryption?

Not every bot does. A bot that only joins unencrypted operational rooms is simpler to deploy and does not need to maintain encryption state. A bot expected to read and reply inside encrypted rooms needs additional dependencies and persistent crypto state.

The Simple-Matrix-Bot-Lib documentation and current matrix-nio documentation both indicate that E2EE relies on matrix-nio's encryption support and libolm. On Debian or Ubuntu, matrix-nio documents installing libolm-dev and then the E2EE extra:

sudo apt-get install libolm-dev
python -m pip install "matrix-nio[e2e]"

Do not enable E2EE just because Matrix supports it. Use it when the rooms require encryption and you are prepared to persist the bot's store and handle device trust. The matrix-nio documentation notes that encryption state, keys, and device trust are stored locally when E2EE is enabled.

Step 3: Create the bot account and keep credentials out of source code

Create a dedicated Matrix account using a client or the account-management process provided by your homeserver. The exact registration UI varies by provider, so this guide does not assume a particular Element screen or claim that open registration is available everywhere.

For development, export three environment variables:

export MATRIX_HOMESERVER="https://matrix.example.com"
export MATRIX_USERNAME="botname"
export MATRIX_PASSWORD="replace-with-a-secret"

Environment variables are convenient for a local tutorial, but they are not automatically a production-grade secret-management system. On a VPS or container platform, prefer the platform's secret store, a protected environment file outside source control, or a dedicated secret manager. Never commit a Matrix password or access token to Git.

Invite the bot account to a test room and accept the invitation with a Matrix client if your server or bot configuration does not auto-join invitations. Start with a private test room. That limits accidental command execution while you validate the bot's behavior.

Step 4: Write, run, and test a minimal command bot

Create bot.py with a small !ping command. The structure below follows the public package example: create Creds, create Bot, add an asynchronous message listener, use MessageMatch, and send a text message through bot.api.

import os
import simplematrixbotlib as botlib

HOMESERVER = os.environ["MATRIX_HOMESERVER"]
USERNAME = os.environ["MATRIX_USERNAME"]
PASSWORD = os.environ["MATRIX_PASSWORD"]
PREFIX = "!"

creds = botlib.Creds(HOMESERVER, USERNAME, PASSWORD)
bot = botlib.Bot(creds)

@bot.listener.on_message_event
async def ping(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)

    if (
        match.is_not_from_this_bot()
        and match.prefix()
        and match.command("ping")
    ):
        await bot.api.send_text_message(room.room_id, "Pong!")

bot.run()

Run it from the activated virtual environment:

python bot.py

In the test room, send:

!ping

A successful result is simple: the bot stays connected, sees the room event, and responds with Pong!. Also confirm that it does not answer its own reply. The is_not_from_this_bot() check is important because a naive echo-style bot can otherwise create feedback loops.

When should you add an allowlist?

Add one before the bot can trigger anything sensitive. A command that only returns “Pong!” has little impact, but a command that runs deployment jobs, queries internal systems, or posts confidential data should not execute for every user in every joined room.

Simple-Matrix-Bot-Lib advertises user access management and allow/blocklist configuration as features. For a production bot, treat authorization as application logic, not as an optional polish step. Restrict by user ID, room ID, or both, and keep server-side permissions on the downstream systems as a second line of defense.

Password login versus access tokens: what is the practical trade-off?

Password login is easy to understand and matches the package's published minimal example. The downside is that a long-running bot must possess the account password, and some modern Matrix deployments may prefer SSO or OAuth flows instead.

Access tokens reduce repeated password use, but token lifecycle rules depend on the authentication system. The Matrix specification says access tokens should be treated as opaque credentials and sent using the HTTP Authorization: Bearer scheme. Current Matrix versions also support expiring access tokens and refresh tokens in some flows. Do not assume that an example written for password credentials automatically handles refresh, revocation, or OAuth.

If token lifecycle, SSO, OAuth, or service-account-style authentication is central to your deployment, verify that capability in the exact Simple-Matrix-Bot-Lib release you install. If the wrapper does not expose enough control, using matrix-nio directly is the cleaner engineering choice.

Should you run the bot on a laptop, VPS, container, or Kubernetes?

For an unencrypted lightweight bot, a small VM or container is usually enough. For an encrypted bot, persistence becomes a design requirement: losing the local crypto store can change device identity and disrupt trust. matrix-nio's E2EE examples emphasize preserving the device ID and encryption store across restarts.

Common setup failures and what they usually mean

• Login fails immediately: confirm the homeserver URL and inspect /_matrix/client/v3/login. A server that does not advertise password login may not work with a password-based quick start.
• The bot starts but never sees messages: confirm the bot account is actually joined to the room and that you are testing with a normal text event.
• The bot replies repeatedly: make sure the handler ignores events sent by the bot itself.
• Encrypted rooms are unreadable: installing the base package is not enough. Add matrix-nio E2EE dependencies, enable encryption according to the library configuration, and preserve the crypto store.
• An old example raises an API error: check your installed package version. The public Simple-Matrix-Bot-Lib docs currently warn that they are unmaintained, so examples may lag the PyPI release.

Which path should you choose?

Choose Simple-Matrix-Bot-Lib when your bot is one Matrix user, your commands are straightforward, and you value concise Python code more than low-level protocol control. It is especially suitable for prototypes, notification bots, room utilities, and small internal automations.

Choose matrix-nio directly when encryption, device verification, custom authentication, event types, sync behavior, or token management are core requirements. You will write more code, but the abstraction boundary is lower and easier to reason about for advanced Matrix work.

Choose an Application Service when your integration is really a homeserver extension, bridge, or gateway rather than a single user bot. The Application Service API is designed for that server-connected model and requires homeserver configuration.

For a first Matrix bot, the minimal !ping example is a good checkpoint: if it can authenticate, join the right room, ignore its own events, and reply reliably, you have validated the basic path. Add encryption, authorization, external APIs, and deployment automation only after that foundation is stable.

Primary references

• Simple-Matrix-Bot-Lib on PyPI — current package metadata, Python requirement, release history, and basic example.
• Simple-Matrix-Bot-Lib documentation — useful historical usage reference; the site currently warns that it may be outdated.
• matrix-nio documentation — underlying client library, E2EE dependencies, storage, and examples.
• Matrix Client-Server API — current authentication, login, token, room, and event protocol behavior.
• Matrix Application Service API — server-integrated alternative for bridges and larger integrations.