Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dbus.service
✓ import dbus.service
✗ from dbus import service
While functional, `import dbus.service` is idiomatic to keep `dbus` namespace clear.
dbus.mainloop.glib.DBusGMainLoop
✓ from dbus.mainloop.glib import DBusGMainLoop
✗ import dbus.mainloop
You typically need the specific mainloop class, not just the module.
This quickstart connects to the system D-Bus and queries the `org.freedesktop.DBus` service to list all currently active service names. This demonstrates basic bus connection, object retrieval, and method invocation. For services that require asynchronous operations (e.g., listening for signals or exposing Python objects), integration with a main event loop (like GLib or Qt) is necessary.
import dbus
try:
# Connect to the system bus
# Use dbus.SessionBus() for the user's session bus
bus = dbus.SystemBus()
# Get the D-Bus 'org.freedesktop.DBus' interface on the bus
obj = bus.get_object('org.freedesktop.DBus', '/org/freedesktop/DBus')
# Get the 'org.freedesktop.DBus' interface itself
iface = dbus.Interface(obj, 'org.freedesktop.DBus')
# Call the ListNames method to get active service names
names = iface.ListNames()
print("Currently active D-Bus service names (system bus):")
for name in names:
print(f"- {name}")
except dbus.exceptions.DBusException as e:
print(f"Error connecting to D-Bus or listing names: {e}")
print("Ensure the D-Bus daemon is running and you have appropriate permissions.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingdbus-python 1.x is Python 3 ONLY. Older versions (e.g., 0.8x) supported Python 2. Directly upgrading from an old Python 2 environment will break existing code.fixEnsure your project runs on Python 3. For Python 2 compatibility, you would need to use an older `dbus-python` version which is not recommended or maintained.
affects: < 1.0.0 to >= 1.0.0
gotchadbus-python requires the underlying C library `libdbus` to be installed on the system. `pip install dbus-python` will install the Python package but will fail at runtime if `libdbus` is missing.fixInstall `libdbus` via your operating system's package manager (e.g., `libdbus-1-dev` or `dbus-libs` on Linux distributions). Using `apt install python3-dbus` (or equivalent) usually installs both the Python bindings and the necessary system libraries.
affects: All versions
gotchaFor D-Bus services that emit signals or require asynchronous handling (e.g., exposing Python objects), `dbus-python` must be integrated with an event loop (e.g., GLib, Qt, Gtk). Without it, your D-Bus service will not respond to calls or process signals.fixImport and initialize a mainloop: `from dbus.mainloop.glib import DBusGMainLoop; DBusGMainLoop(set_as_default=True)`. Then run the GLib main loop: `from gi.repository import GLib; loop = GLib.MainLoop(); loop.run()` or similar for other toolkits.
affects: All versions
gotchaD-Bus concepts (Bus, Object Paths, Interfaces, Service Names) are fundamental. Misunderstanding these often leads to connection errors or services not being found.fixFamiliarize yourself with the D-Bus specification and common usage patterns. The `dbus-python` documentation and the official D-Bus tutorial are good starting points.
affects: All versions
Upgrade
Version history
1.4.0latest on PyPI · released Mar 13, 2025
Audit
Dependencies
No dependency data recorded yet.