{"id":13725395,"url":"https://github.com/systemd/pystemd","last_synced_at":"2026-01-16T07:10:33.352Z","repository":{"id":26684379,"uuid":"107490240","full_name":"systemd/pystemd","owner":"systemd","description":"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.","archived":false,"fork":false,"pushed_at":"2026-01-12T21:33:13.000Z","size":321,"stargazers_count":456,"open_issues_count":16,"forks_count":40,"subscribers_count":17,"default_branch":"main","last_synced_at":"2026-01-13T01:54:05.763Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/systemd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-10-19T02:50:05.000Z","updated_at":"2026-01-12T21:33:28.000Z","dependencies_parsed_at":"2024-04-22T09:02:28.279Z","dependency_job_id":"a0c16b0a-d154-4721-9489-10c085871d6b","html_url":"https://github.com/systemd/pystemd","commit_stats":null,"previous_names":["facebookincubator/pystemd"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/systemd/pystemd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fpystemd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fpystemd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fpystemd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fpystemd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/systemd","download_url":"https://codeload.github.com/systemd/pystemd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fpystemd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:02:21.707Z","updated_at":"2026-01-16T07:10:33.345Z","avatar_url":"https://github.com/systemd.png","language":"Python","readme":"pystemd\n=======\n\n[![Continuous Integration](https://github.com/systemd/pystemd/workflows/Continuous%20Integration/badge.svg?event=push)](https://github.com/systemd/pystemd/actions) [![Matrix](https://img.shields.io/matrix/pystemd:matrix.org)](https://matrix.to/#/#pystemd:matrix.org)\n\n\nThis library allows you to talk to systemd over D-Bus from Python, without\nactually thinking that you are talking to systemd over D-Bus. This allows you to\nprogrammatically start/stop/restart/kill and verify service status from\nsystemd's point of view, avoiding executing `subprocess.Popen(['systemctl', ...`\nand then parsing the output to know the result.\n\n\nShow don't tell\n---------------\n\nIn software as in screenwriting, it's better to show how things work instead of\ntell. So this is how you would use the library from an interactive shell.\n\n    In [1]: from pystemd.systemd1 import Unit\n    In [2]: unit = Unit(b'postfix.service')\n    In [3]: unit.load()\n\nNote: you need to call `unit.load()` because by default `Unit` will not load the\nunit information as that would require doing some I/O (and we don't like doing I/O in a class constructor).\nYou can autoload the unit by `Unit(b'postfix.service', _autoload=True)` or using the unit as a\ncontext manager like `with Unit(b'postfix.service'): ...`\n\nOnce the unit is loaded, you can interact with it by accessing its\nsystemd interfaces:\n\n    In [4]: unit.Unit.ActiveState\n    Out[4]: b'active'\n\n    In [5]: unit.Unit.StopWhenUnneeded\n    Out[5]: False\n\n    In [6]: unit.Unit.Stop(b'replace') # requires a privileged account\n    Out[6]: b'/org/freedesktop/systemd1/job/6601531'\n\n    In [7]: unit.Unit.ActiveState\n    Out[7]: b'inactive'\n\n    In [8]: unit.Unit.SubState\n    Out[8]: b'running'\n\n    In [9]: unit.Unit.Start(b'replace') # requires a privileged account\n    Out[9]: b'/org/freedesktop/systemd1/job/6601532'\n\n    In [10]: unit.Unit.ActiveState\n    Out[10]: b'active'\n\n    In [11]: unit.Service.GetProcesses() # requires systemd v238 and above\n    Out[11]:\n    [(b'/system.slice/postfix.service',\n        1754222,\n        b'/usr/libexec/postfix/master -w'),\n     (b'/system.slice/postfix.service', 1754224, b'pickup -l -t fifo -u'),\n     (b'/system.slice/postfix.service', 1754225, b'qmgr -l -t fifo -u')]\n\n    In [12]: unit.Service.MainPID\n    Out[12]: 1754222\n\nThe `systemd1.Unit` class provides shortcuts for the interfaces in the systemd\nnamespace. As shown above, we have Service (org.freedesktop.systemd1.Service)\nand Unit (org.freedesktop.systemd1.Unit). Others can be found in\n`unit._interfaces`:\n\n```\nIn [12]: unit._interfaces\nOut[12]:\n{'org.freedesktop.DBus.Introspectable': \u003corg.freedesktop.DBus.Introspectable of /org/freedesktop/systemd1/unit/postfix_2eservice\u003e,\n 'org.freedesktop.DBus.Peer': \u003corg.freedesktop.DBus.Peer of /org/freedesktop/systemd1/unit/postfix_2eservice\u003e,\n 'org.freedesktop.DBus.Properties': \u003corg.freedesktop.DBus.Properties of /org/freedesktop/systemd1/unit/postfix_2eservice\u003e,\n 'org.freedesktop.systemd1.Service': \u003corg.freedesktop.systemd1.Service of /org/freedesktop/systemd1/unit/postfix_2eservice\u003e,\n 'org.freedesktop.systemd1.Unit': \u003corg.freedesktop.systemd1.Unit of /org/freedesktop/systemd1/unit/postfix_2eservice\u003e}\n\n In [13]: unit.Service\n Out[13]: \u003corg.freedesktop.systemd1.Service of /org/freedesktop/systemd1/unit/postfix_2eservice\u003e\n```\n\nEach interface has methods and properties that you can access directly as\n`unit.Service.MainPID`. The list of properties and methods is in `.properties`\nand `.methods` of each interface.\n\nThe 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:\n```\nfrom pystemd.dbuslib import DBus\nwith DBus(user_mode=True) as bus:\n    unit = Unit(b\"postfix.service\", bus=bus)\n    unit.load()\n```\n\nAlongside `systemd1.Unit`, we also have `systemd1.Manager`, which allows\nyou to interact with the systemd manager.\n\n\n```\nIn [14]: from pystemd.systemd1 import Manager\n\nIn [15]: manager = Manager()\n\nIn [16]: manager.load()\n\nIn [17]: manager.Manager.ListUnitFiles()\nOut[17]:\n...\n(b'/usr/lib/systemd/system/rhel-domainname.service', b'disabled'),\n (b'/usr/lib/systemd/system/fstrim.timer', b'disabled'),\n (b'/usr/lib/systemd/system/getty.target', b'static'),\n (b'/usr/lib/systemd/system/systemd-user-sessions.service', b'static'),\n...\n\nIn [18]: manager.Manager.Architecture\nOut[18]: b'x86-64'\n\nIn [19]: manager.Manager.Virtualization\nOut[19]: b'kvm'\n\n```\n\nExtras\n------\nWe also include `pystemd.run`, the spiritual port of systemd-run\nto Python. [Example of usage](_docs/pystemd.run.md):\n\n```python\n# run this as root\n\u003e\u003e\u003e import pystemd.run, sys\n\u003e\u003e\u003e pystemd.run(\n    [b'/usr/bin/psql', b'postgres'],\n    machine=b'db1',\n    user=b'postgres',\n    wait=True,\n    pty=True,\n    stdin=sys.stdin, stdout=sys.stdout,\n    env={b'PGTZ': b'UTC'}\n)\n```\n\nwill open a PostgreSQL interactive prompt in a local nspawn machine.\n\nYou also get an interface to `sd_notify` in the form of `pystemd.daemon.notify` [docs](_docs/daemon.md).\n\n```python\n# run this as root\n\u003e\u003e\u003e import pystemd.daemon\n\u003e\u003e\u003e pystemd.daemon.notify(False, ready=1, status='Gimme! Gimme! Gimme!')\n```\n\nAnd access to listen file descriptors for socket-activated scripts.\n\n```python\n# run this as root\n\u003e\u003e\u003e import pystemd.daemon\n\u003e\u003e\u003e pystemd.daemon.LISTEN_FDS_START\n3\n\u003e\u003e\u003e pystemd.daemon.listen_fds()\n1 # you normally only open 1 socket\n```\n\nAnd access to check if watchdog is enabled and ping it.\n\n```python\nimport time\nimport pystemd.daemon\n\nwatchdog_usec = pystemd.daemon.watchdog_enabled()\nwatchdog_sec = watchdog_usec/10**6\n\nif not watchdog_usec:\n  print('watchdog was not enabled!')\n\nfor i in range(20):\n    pystemd.daemon.notify(False, watchdog=1, status=f'count {i+1}')\n    time.sleep(watchdog_sec*0.5)\n\nprint('sleeping for 30 seconds')\ntime.sleep(watchdog_sec*2)\nprint('you will never reach me in a watchdog env')\n\n```\n\nWe also provide basic journal interaction with `pystemd.journal` [docs](_docs/journal.md)\n\n```python\nimport logging\nimport pystemd.journal\n\npystemd.journal.sendv(\n  f\"PRIORITY={logging.INFO}\",\n  MESSAGE=\"everything is awesome\",\n  SYSLOG_IDENTIFIER=\"tegan\"\n)\n```\n\nwill result in the following message (shortened for the sake of the example).\n\n```json\n\n{\n\n  \"SYSLOG_IDENTIFIER\" : \"tegan\",\n  \"PRIORITY\" : \"20\",\n  \"MESSAGE\" : \"everything is awesome\",\n  ...\n}\n\n```\n\nInstall\n-------\n\nIf you like what you see, the simplest way to install pystemd is:\n\n```bash\n$ pip install pystemd\n```\n\npystemd is packaged in a few distros like Fedora and Debian. It is available in Fedora 32+ and in EPEL 8+.\n\nIt can be installed with:\n\n```bash\n$ sudo dnf install python3-pystemd # fedora\n$ sudo apt install python3-pystemd # debian\n```\n\nwhich 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.\n\n\nBuild from source\n-----------------\n\n\nYou'll need to have:\n\n* Python headers: Just use your distro's package (e.g. python-dev).\n* systemd headers: Chances are you already have this. Normally, it is called\n`libsystemd-dev` or `systemd-devel`. You need to have at least v237.\nPlease note that CentOS 7 ships with version 219. To work around this, please read\n  [this](_docs/centos7.md).\n* systemd library: check if `pkg-config --cflags --libs libsystemd` returns\n`-lsystemd` if not you can install `systemd-libs` or\n`libsystemd` depending on your distribution, version needs to be at least\nv237.\n* gcc: or any compiler that `setup.py` will accept.\n* [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) command. Depending on your distro, the package is called \"pkg-config\", \"pkgconfig\" or a compatible substitute like \"pkgconf\"\n\nIf you want to install from source, after cloning this repo all you need to do is `pip install .`\n\n\nIn addition to the previous requirements, you'll need:\n\n  * setuptools: Just use your distro's package (e.g. python-setuptools).\n  * Cython: at least version 0.21a1. Just pip install it or use the official\n  installation guide from the Cython homepage to get the latest version:\n   http://cython.readthedocs.io/en/latest/src/quickstart/install.html.\n\n\nLearning more\n-------------\n\nThis project has been covered in a number of conference talks:\n* [Using systemd in high level languages](https://www.youtube.com/watch?v=lBQgMGPxqNo) at [All Systems Go! 2018](https://all-systems-go.io)\n* [systemd: why you should care as a Python developer](https://www.youtube.com/watch?v=ZUX9Fx8Rwzg) at [PyCon 2018](https://us.pycon.org/2018/)\n* [Better security for Python with systemd](https://www.youtube.com/watch?v=o-OqslA5dkw) at [Pyninsula #10](https://www.meetup.com/Pyninsula-Python-Peninsula-Meetup/events/244939632/)\n\nA [Vagrant-based demo](https://github.com/aleivag/pycon2018) was also developed\nfor PyCon 2018.\n\nLicense\n-------\n\npystemd is licensed under LGPL 2.1 or later.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemd%2Fpystemd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystemd%2Fpystemd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemd%2Fpystemd/lists"}