Remove the optional systemd-python dependency (#19491)

Summary
- drop the `systemd` extra from `pyproject.toml` and the
`systemd-python` optional dependency
- this means we don't ship the journald log handler, so it clarifies the
docs how to install that in the venv
- ensure the Debian virtualenv build keeps shipping
`systemd-python>=231` in the venv, so the packaged log config can keep
using `systemd.journal.JournalHandler`

Context of this is the following:

> Today in my 'how hard would it be to move to uv' journey:
https://github.com/systemd/python-systemd/issues/167
>
> The gist of it is that uv really wants to create a universal lock
file, which means it needs to be able to resolve the package metadata,
even for packages locked for other platforms. In the case of
systemd-python, they use mesonpy as build backend, which doesn't
implement prepare_metadata_for_build_wheel, which means it needs to run
meson to be able to resolve the package metadata. And it will hard-fail
if libsystemd dev headers aren't available 😭
>
> [*message in
#synapse-dev:matrix.org*](https://matrix.to/#/!i5D5LLct_DYG-4hQprLzrxdbZ580U9UB6AEgFnk6rZQ/$OKLB3TJVXAwq43sAZFJ-_PvMMzl4P_lWmSAtlmsoMuM?via=element.io&via=matrix.org&via=beeper.com)

changelog.d/19491.misc

@@ -0,0 +1 @@
+Remove the optional `systemd-python` dependency and the `systemd` extra on the `synapse` package.

contrib/systemd/README.md

@@ -16,3 +16,9 @@ appropriate locations of your installation.
 5. Start Synapse: `sudo systemctl start matrix-synapse`
 6. Verify Synapse is running: `sudo systemctl status matrix-synapse`
 7. *optional* Enable Synapse to start at system boot: `sudo systemctl enable matrix-synapse`
+
+## Logging
+
+If you use `contrib/systemd/log_config.yaml`, install `systemd-python` in the
+same Python environment as Synapse. The config uses
+`systemd.journal.JournalHandler`, which requires that package.

contrib/systemd/log_config.yaml

@@ -1,5 +1,6 @@
 version: 1
 
+# Requires the `systemd-python` package in Synapse's runtime environment.
 # In systemd's journal, loglevel is implicitly stored, so let's omit it
 # from the message text.
 formatters:

debian/build_virtualenv

@@ -39,8 +39,10 @@ pip install poetry==2.1.1 poetry-plugin-export==1.9.0
 poetry export \
     --extras all \
     --extras test \
-    --extras systemd \
     -o exported_requirements.txt
+# Keep journald logging support in the packaged virtualenv when using
+# systemd.journal.JournalHandler in /etc/matrix-synapse/log.yaml.
+echo "systemd-python==235 --hash=sha256:4e57f39797fd5d9e2d22b8806a252d7c0106c936039d1e71c8c6b8008e695c0a" >> exported_requirements.txt
 deactivate
 rm -rf "$TEMP_VENV"
 
@@ -57,7 +59,7 @@ dh_virtualenv \
     --extra-pip-arg="--no-deps" \
     --extra-pip-arg="--no-cache-dir" \
     --extra-pip-arg="--compile" \
-    --extras="all,systemd,test" \
+    --extras="all,test" \
     --requirements="exported_requirements.txt"
 
 PACKAGE_BUILD_DIR="$(pwd)/debian/matrix-synapse-py3"

debian/changelog

@@ -1,3 +1,9 @@
+matrix-synapse-py3 (1.149.0~rc1+nmu1) UNRELEASED; urgency=medium
+
+  * Change how the systemd journald integration is installed.
+
+ -- Quentin Gliech <packages@matrix.org>  Fri, 20 Feb 2026 19:19:51 +0100
+
 matrix-synapse-py3 (1.149.0~rc1) stable; urgency=medium
 
   * New synapse release 1.149.0rc1.

docs/setup/installation.md

@@ -229,6 +229,11 @@ pip install --upgrade setuptools
 pip install matrix-synapse
 ```
 
+If you want to use a logging configuration that references
+`systemd.journal.JournalHandler` (for example `contrib/systemd/log_config.yaml`),
+you must install `systemd-python` separately in the same environment.
+Synapse no longer provides a `matrix-synapse[systemd]` extra.
+
 This will download Synapse from [PyPI](https://pypi.org/project/matrix-synapse)
 and install it, along with the python libraries it uses, into a virtual environment
 under `~/synapse/env`.  Feel free to pick a different directory if you

docs/upgrade.md

@@ -117,6 +117,22 @@ each upgrade are complete before moving on to the next upgrade, to avoid
 stacking them up. You can monitor the currently running background updates with
 [the Admin API](usage/administration/admin_api/background_updates.html#status).
 
+# Upgrading to v1.150.0
+
+## Removal of the `systemd` pip extra
+
+The `matrix-synapse[systemd]` pip extra has been removed.
+If you use `systemd.journal.JournalHandler` in your logging configuration
+(e.g. `contrib/systemd/log_config.yaml`), you must now install
+`systemd-python` manually in Synapse's runtime environment:
+
+```bash
+pip install systemd-python
+```
+
+No action is needed if you do not use journal logging, or if you installed
+Synapse from the Debian packages (which handle this automatically).
+
 # Upgrading to v1.146.0
 
 ## Drop support for Ubuntu 25.04 Plucky Puffin, and add support for 25.10 Questing Quokka

docs/usage/configuration/logging_sample_config.md

@@ -14,6 +14,9 @@ It should be named `<SERVERNAME>.log.config` by default.
 Hint: If you're looking for a guide on what each of the fields in the "Processed request" log lines mean,
 see [Request log format](../administration/request_log.md).
 
+If you use `systemd.journal.JournalHandler` in your own logging config, ensure
+`systemd-python` is installed in Synapse's runtime environment.
+
 ```yaml
 {{#include ../../sample_log_config.yaml}}
 ```

poetry.lock

@@ -3128,18 +3128,6 @@ c = ["sqlglotc"]
 dev = ["duckdb (>=0.6)", "mypy", "pandas", "pandas-stubs", "pdoc", "pre-commit", "pyperf", "python-dateutil", "pytz", "ruff (==0.7.2)", "types-python-dateutil", "types-pytz", "typing_extensions"]
 rs = ["sqlglotrs (==0.13.0)"]
 
-[[package]]
-name = "systemd-python"
-version = "235"
-description = "Python interface for libsystemd"
-optional = true
-python-versions = "*"
-groups = ["main"]
-markers = "extra == \"systemd\""
-files = [
-    {file = "systemd-python-235.tar.gz", hash = "sha256:4e57f39797fd5d9e2d22b8806a252d7c0106c936039d1e71c8c6b8008e695c0a"},
-]
-
 [[package]]
 name = "threadloop"
 version = "1.0.2"
@@ -3761,11 +3749,10 @@ postgres = ["psycopg2", "psycopg2cffi", "psycopg2cffi-compat"]
 redis = ["hiredis", "txredisapi"]
 saml2 = ["defusedxml", "pysaml2", "pytz"]
 sentry = ["sentry-sdk"]
-systemd = ["systemd-python"]
 test = ["idna", "parameterized"]
 url-preview = ["lxml"]
 
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.10.0,<4.0.0"
-content-hash = "1caa5072f6304122c89377420f993a54f54587f3618ccc8094ec31642264592c"
+content-hash = "dd63614889e7e181fca33760741a490e65fe4ef4f42756cafd0f804ae7324916"

pyproject.toml

@@ -135,10 +135,6 @@ saml2 = [
     "pytz>=2018.3",  # via pysaml2
 ]
 oidc = ["authlib>=0.15.1"]
-# systemd-python is necessary for logging to the systemd journal via
-# `systemd.journal.JournalHandler`, as is documented in
-# `contrib/systemd/log_config.yaml`.
-systemd = ["systemd-python>=231"]
 url-preview = ["lxml>=4.6.3"]
 sentry = ["sentry-sdk>=0.7.2"]
 opentracing = [
@@ -194,7 +190,6 @@ all = [
     "pympler>=1.0",
     # omitted:
     #   - test: it's useful to have this separate from dev deps in the olddeps job
-    #   - systemd: this is a system-based requirement
 
     # Transitive dependencies
     # These dependencies aren't directly required by Synapse.