468 GitHub stars and counting — systemd/pystemd is a Python project TopGit is tracking across repositories on the platform. A thin Cython-based wrapper on top of libsystemd, focused on exposing the dbus API via sd-bus in an automated and easy to consume way.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
This library allows you to talk to systemd over D-Bus from Python, without
actually thinking that you are talking to systemd over D-Bus. This allows you to
programmatically start/stop/restart/kill and verify service status from
systemd's point of view, avoiding executing subprocess.Popen(['systemctl', ...
and then parsing the output to know the result.
Show don't tell
In software as in screenwriting, it's better to show how things work instead of
tell. So this is how you would use the library from an interactive shell.
In [1]: from pystemd.systemd1 import Unit
In [2]: unit = Unit(b'postfix.service')
In [3]: unit.load()
Note: you need to call unit.load() because by default Unit will not load the
unit information as that would require doing some I/O (and we don't like doing I/O in a class constructor).
You can autoload the unit by Unit(b'postfix.service', _autoload=True) or using the unit as a
context manager like with Unit(b'postfix.service'): ...
Once the unit is loaded, you can interact with it by accessing its
systemd interfaces:
In [4]: unit.Unit.ActiveState
Out[4]: b'active'
In [5]: unit.Unit.StopWhenUnneeded
Out[5]: False
In [6]: unit.Unit.Stop(b'replace') # requires a privileged account
Out[6]: b'/org/freedesktop/systemd1/job/6601531'
In [7]: unit.Unit.ActiveState
Out[7]: b'inactive'
In [8]: unit.Unit.SubState
Out[8]: b'running'
In [9]: unit.Unit.Start(b'replace') # requires a privileged account
Out[9]: b'/org/freedesktop/systemd1/job/6601532'
In [10]: unit.Unit.ActiveState
Out[10]: b'active'
In [11]: unit.Service.GetProcesses() # requires systemd v238 and above
Out[11]:
[(b'/system.slice/postfix.service',
1754222,
b'/usr/libexec/postfix/master -w'),
(b'/system.slice/postfix.service', 1754224, b'pickup -l -t fifo -u'),
(b'/system.slice/postfix.service', 1754225, b'qmgr -l -t fifo -u')]
In [12]: unit.Service.MainPID
Out[12]: 1754222
The systemd1.Unit class provides shortcuts for the interfaces in the systemd
namespace. As shown above, we have Service (org.freedesktop.systemd1.Service)
and Unit (org.freedesktop.systemd1.Unit). Others can be found in
unit._interfaces:
In [12]: unit._interfaces
Out[12]:
{'org.freedesktop.DBus.Introspectable': <org.freedesktop.DBus.Introspectable of /org/freedesktop/systemd1/unit/postfix_2eservice>,
'org.freedesktop.DBus.Peer': <org.freedesktop.DBus.Peer of /org/freedesktop/systemd1/unit/postfix_2eservice>,
'org.freedesktop.DBus.Properties': <org.freedesktop.DBus.Properties of /org/freedesktop/systemd1/unit/postfix_2eservice>,
'org.freedesktop.systemd1.Service': <org.freedesktop.systemd1.Service of /org/freedesktop/systemd1/unit/postfix_2eservice>,
'org.freedesktop.systemd1.Unit': <org.freedesktop.systemd1.Unit of /org/freedesktop/systemd1/unit/postfix_2eservice>}
In [13]: unit.Service
Out[13]: <org.freedesktop.systemd1.Service of /org/freedesktop/systemd1/unit/postfix_2eservice>
Each interface has methods and properties that you can access directly as
unit.Service.MainPID. The list of properties and methods is in .properties
and .methods of each interface.
The above code operates on system (a.k.a root) units by default. To operate on user units, explicitly pass in a user mode D-Bus instance:
from pystemd.dbuslib import DBus
with DBus(user_mode=True) as bus:
unit = Unit(b"postfix.service", bus=bus)
unit.load()
Alongside systemd1.Unit, we also have systemd1.Manager, which allows
you to interact with the systemd manager.
In [14]: from pystemd.systemd1 import Manager
In [15]: manager = Manager()
In [16]: manager.load()
In [17]: manager.Manager.ListUnitFiles()
Out[17]:
...
(b'/usr/lib/systemd/system/rhel-domainname.service', b'disabled'),
(b'/usr/lib/systemd/system/fstrim.timer', b'disabled'),
(b'/usr/lib/systemd/system/getty.target', b'static'),
(b'/usr/lib/systemd/system/systemd-user-sessions.service', b'static'),
...
In [18]: manager.Manager.Architecture
Out[18]: b'x86-64'
In [19]: manager.Manager.Virtualization
Out[19]: b'kvm'
Extras
We also include pystemd.run, the spiritual port of systemd-run
to Python. Example of usage:
# run this as root
>>> import pystemd.run, sys
>>> pystemd.run(
[b'/usr/bin/psql', b'postgres'],
machine=b'db1',
user=b'postgres',
wait=True,
pty=True,
stdin=sys.stdin, stdout=sys.stdout,
env={b'PGTZ': b'UTC'}
)
will open a PostgreSQL interactive prompt in a local nspawn machine.
You also get an interface to sd_notify in the form of pystemd.daemon.notify docs.
# run this as root
>>> import pystemd.daemon
>>> pystemd.daemon.notify(False, ready=1, status='Gimme! Gimme! Gimme!')
And access to listen file descriptors for socket-activated scripts.
# run this as root
>>> import pystemd.daemon
>>> pystemd.daemon.LISTEN_FDS_START
3
>>> pystemd.daemon.listen_fds()
1 # you normally only open 1 socket
And access to check if watchdog is enabled and ping it.
import time
import pystemd.daemon
watchdog_usec = pystemd.daemon.watchdog_enabled()
watchdog_sec = watchdog_usec/10**6
if not watchdog_usec:
print('watchdog was not enabled!')
for i in range(20):
pystemd.daemon.notify(False, watchdog=1, status=f'count {i+1}')
time.sleep(watchdog_sec*0.5)
print('sleeping for 30 seconds')
time.sleep(watchdog_sec*2)
print('you will never reach me in a watchdog env')
We also provide basic journal interaction with pystemd.journal docs
which will also take care of installing any required dependencies. Keep in mind that most distros manage their own repos and versions, so you may be getting older versions.
Build from source
You'll need to have:
Python headers: Just use your distro's package (e.g. python-dev).
systemd headers: Chances are you already have this. Normally, it is called
libsystemd-dev or systemd-devel. You need to have at least v237.
Please note that CentOS 7 ships with version 219. To work around this, please read
this.
systemd library: check if pkg-config --cflags --libs libsystemd returns
-lsystemd if not you can install systemd-libs or
libsystemd depending on your distribution, version needs to be at least
v237.
gcc: or any compiler that setup.py will accept.
pkg-config command. Depending on your distro, the package is called "pkg-config", "pkgconfig" or a compatible substitute like "pkgconf"
If you want to install from source, after cloning this repo all you need to do is pip install .
In addition to the previous requirements, you'll need:
setuptools: Just use your distro's package (e.g. python-setuptools).
Cython: at least version 0.21a1. Just pip install it or use the official
installation guide from the Cython homepage to get the latest version:
http://cython.readthedocs.io/en/latest/src/quickstart/install.html.
Learning more
This project has been covered in a number of conference talks:
Using systemd in high level languages at All Systems Go! 2018
systemd: why you should care as a Python developer at PyCon 2018
Better security for Python with systemd at Pyninsula #10
A Vagrant-based demo was also developed
for PyCon 2018.
No homepage URL was recorded for systemd/pystemd in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Is systemd/pystemd open source?
Yes — systemd/pystemd ships under the LGPL-2.1 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/systemd/pystemd.
What is systemd/pystemd?
systemd/pystemd (systemd/pystemd) is a Python project on GitHub. From the project's own README: A thin Cython-based wrapper on top of libsystemd, focused on exposing the dbus API via sd-bus in an automated and easy to consume way.
What license does systemd/pystemd use?
systemd/pystemd is released under the LGPL-2.1 license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about systemd/pystemd?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/systemd/pystemd is the definitive source.
Read full README in the tab above.
Curious whether pystemd is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about pystemd.