Matrix Synapse

1.152.0 verified Fri May 01 auth: no python

Synapse is the reference homeserver for the Matrix decentralized communication protocol. As of version 1.152.0, it requires Python 3.10+ and follows a rapid release cadence. This package provides the server backend, not a client library.

pip install matrix-synapse

Common errors

error ImportError: cannot import name 'MatrixClient' from 'matrix_client' ↓

cause Confusion between server package and client library. matrix-synapse does not provide a MatrixClient.

fix

Use matrix-nio: pip install matrix-nio; from nio import AsyncClient

error synapse module not found or python: can't open file 'synctl': [Errno 2] No such file or directory ↓

cause synctl is not installed as a script; must be run from the source tree or use python -m synapse.app.homeserver.

fix

Run: python -m synapse.app.homeserver --server-name my.domain --config-path homeserver.yaml --generate-config

Warnings

breaking Synapse 1.96 dropped support for Python 3.7 and 3.8; 1.110 dropped Python 3.9. Upgrade to Python 3.10+. ↓

fix Ensure your environment uses Python 3.10 or later.

gotcha Do not pip install matrix-synapse expecting a client library. Synapse is a server. For Python clients, use matrix-nio or matrix-client. ↓

fix Use matrix-nio for client SDK: pip install matrix-nio

breaking Configuration format changes between major versions; old config files may break. Especially the transition to YAML-only and removal of legacy options. ↓

fix Review upgrade notes at https://matrix-org.github.io/synapse/latest/upgrade.html

Imports

synapse module
```
import synapse
```
Synapse is a server package, not typically imported as a library. Use 'import synapse' only for internal modules.

Quickstart

Synapse is a server; quickstart shows how to generate config and run.

# Synapse is a server application, not a library for direct import.
# To run it, use the command line:
# python -m synapse.app.homeserver --server-name my.domain --config-path homeserver.yaml --generate-config
# For development, install and then start:
# install via pip, then run:
# synctl start
print('Synapse is a server; see https://matrix-org.github.io/synapse/latest/')