systemd-python

235 · active · verified Thu Apr 16

systemd-python provides a Python interface for libsystemd, allowing Python applications to interact with systemd components like the journal, daemon management, and unit control. The current version is 235. Releases are infrequent and typically tied to major systemd project releases.

Common errors

```
ModuleNotFoundError: No module named 'systemd'
```
cause The `systemd-python` package is not installed for the active Python environment, or it was installed via a system package manager but for a different Python interpreter.

fix Install the package: `pip install systemd-python` or for system-wide use, use your distribution's package manager: `sudo apt install python3-systemd` (Debian/Ubuntu) or `sudo dnf install python3-systemd` (Fedora/RHEL).
```
ImportError: cannot import name 'Journal' from 'systemd' (possibly 'systemd.journal')
```
cause The `Journal` class is located within the `systemd.journal` submodule, not directly under `systemd`.

fix Change the import statement to `from systemd.journal import Journal`.
```
systemd.journal.JournaldError: Failed to connect to journal: Protocol error
```
cause The Python script is not running on a systemd-based Linux system, `systemd-journald` is not active, or the current user lacks permissions to access the journal.

fix Verify that you are running on a Linux system with systemd. Check the status of `systemd-journald` (`systemctl status systemd-journald`). Ensure the user has read access to the journal (e.g., by being in the `systemd-journal` or `adm` group, or running as root for testing).

Warnings

gotcha Direct `pip install systemd-python` is often discouraged on systemd-based Linux distributions. It's generally safer and recommended to use the distribution's provided package (e.g., `apt install python3-systemd` on Debian/Ubuntu, `dnf install python3-systemd` on Fedora/RHEL) to ensure compatibility with the system's `libsystemd`.
Fix: Prefer using your distribution's package manager to install `python3-systemd`.
breaking `systemd-python` is specifically designed for Linux systems utilizing systemd. It will not work on other operating systems (like macOS, Windows) or Linux distributions that do not use systemd (like Alpine Linux with OpenRC). Attempting to use it elsewhere will result in various errors, including `ModuleNotFoundError` or errors when trying to connect to systemd services.
Fix: Ensure your environment is a systemd-based Linux distribution. For cross-platform applications, consider abstracting systemd-specific functionality.
gotcha The API is a low-level binding to `libsystemd`. Error handling often involves checking return codes, handling `JournaldError` or `SystemdError` exceptions, and understanding systemd-specific error messages, which can be less 'Pythonic' than other libraries. Some operations may require elevated privileges (e.g., interacting with D-Bus for unit control).
Fix: Consult systemd documentation for specific error codes and expected behavior. Implement robust `try-except` blocks for `systemd.journal.JournaldError` or `systemd.SystemdError`. Be mindful of process privileges.

Install

pip install systemd-python Install with pip
sudo apt install python3-systemd Debian/Ubuntu (recommended)
sudo dnf install python3-systemd Fedora/RHEL (recommended)

Imports

Journal
wrong:
```
from systemd import Journal
```
correct:
```
from systemd.journal import Journal
```
Journal class is within the 'journal' submodule.
daemon.notify
```
from systemd import daemon
```
Daemon readiness and notification functions are directly under the 'systemd.daemon' module.

Quickstart

This quickstart demonstrates how to send a log message to the systemd journal using the `Journal` class. It includes custom fields for better discoverability and provides an error message if systemd-journald is not available, which is common when running on non-systemd systems or without proper access.

import os
from systemd.journal import Journal

# Get an environment variable, useful for identifying the service in the journal
service_identifier = os.environ.get('SYSTEMD_UNIT', 'my_python_script.service')

try:
    # Initialize the Journal object
    j = Journal()

    # Send a message to the systemd journal
    j.send(
        f'Hello from systemd-python! Test message from {service_identifier}.',
        PRIORITY='INFO',
        PYTHON_PROCESS=os.getpid(), # Example custom field
        SERVICE_NAME=service_identifier # Another custom field
    )
    print(f"Message successfully sent to systemd journal from {service_identifier}.")
except Exception as e:
    print(f"Failed to send message to systemd journal: {e}")
    print("Note: This script must be run on a Linux system with systemd-journald active and accessible.")
    print("You can view journal entries using: journalctl -f -t python-script")

view raw JSON →