{"id":7773,"library":"systemd-python","title":"systemd-python","description":"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.","status":"active","version":"235","language":"en","source_language":"en","source_url":"https://github.com/systemd/python-systemd","tags":["systemd","linux","daemon","journald","system_integration","low-level"],"install":[{"cmd":"pip install systemd-python","lang":"bash","label":"Install with pip"},{"cmd":"sudo apt install python3-systemd","lang":"bash","label":"Debian/Ubuntu (recommended)"},{"cmd":"sudo dnf install python3-systemd","lang":"bash","label":"Fedora/RHEL (recommended)"}],"dependencies":[],"imports":[{"note":"Journal class is within the 'journal' submodule.","wrong":"from systemd import Journal","symbol":"Journal","correct":"from systemd.journal import Journal"},{"note":"Daemon readiness and notification functions are directly under the 'systemd.daemon' module.","symbol":"daemon.notify","correct":"from systemd import daemon"}],"quickstart":{"code":"import os\nfrom systemd.journal import Journal\n\n# Get an environment variable, useful for identifying the service in the journal\nservice_identifier = os.environ.get('SYSTEMD_UNIT', 'my_python_script.service')\n\ntry:\n    # Initialize the Journal object\n    j = Journal()\n\n    # Send a message to the systemd journal\n    j.send(\n        f'Hello from systemd-python! Test message from {service_identifier}.',\n        PRIORITY='INFO',\n        PYTHON_PROCESS=os.getpid(), # Example custom field\n        SERVICE_NAME=service_identifier # Another custom field\n    )\n    print(f\"Message successfully sent to systemd journal from {service_identifier}.\")\nexcept Exception as e:\n    print(f\"Failed to send message to systemd journal: {e}\")\n    print(\"Note: This script must be run on a Linux system with systemd-journald active and accessible.\")\n    print(\"You can view journal entries using: journalctl -f -t python-script\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Prefer using your distribution's package manager to install `python3-systemd`.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your environment is a systemd-based Linux distribution. For cross-platform applications, consider abstracting systemd-specific functionality.","message":"`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.","severity":"breaking","affected_versions":"All"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","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.","error":"ModuleNotFoundError: No module named 'systemd'"},{"fix":"Change the import statement to `from systemd.journal import Journal`.","cause":"The `Journal` class is located within the `systemd.journal` submodule, not directly under `systemd`.","error":"ImportError: cannot import name 'Journal' from 'systemd' (possibly 'systemd.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).","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.","error":"systemd.journal.JournaldError: Failed to connect to journal: Protocol error"}]}