libvirt-python binding for Libvirt API

Common errors

• ImportError: No module named 'libvirt'

  cause The `libvirt-python` package is not installed, or the underlying `libvirt` C library is missing or cannot be found by the Python binding.
  fix First, `pip install libvirt-python`. Second, ensure the `libvirt` development package (e.g., `libvirt-dev` on Debian/Ubuntu, `libvirt-devel` on RHEL/Fedora) is installed on your system. Also, verify `libvirtd` service is running.

• libvirt.libvirtError: Failed to connect to socket

  cause The libvirtd daemon is not running, the connection URI is incorrect, or required permissions are not met.
  fix Verify the `libvirtd` service is running (`sudo systemctl status libvirtd`). Check your connection URI (e.g., `qemu:///system`, `qemu:///session`, `tcp://hostname:port/system`). Ensure the user running the Python script has appropriate permissions (e.g., in the `libvirt` group).

• libvirt.libvirtError: internal error: Client and server are in different primary groups

  cause A common issue on some systems where the user is not in the `libvirt` group or the `libvirt` group ID differs, preventing connections to `qemu:///system`.
  fix Add your user to the `libvirt` group (`sudo usermod -a -G libvirt $USER`) and log out/in for changes to take effect. Alternatively, connect to `qemu:///session` for user-level virtualization.

Warnings

• gotcha The `libvirt-python` package is a binding to the `libvirt` C library. You must have the `libvirt` C library (and often its development headers) installed on your system for `libvirt-python` to work. Installing just the Python package is insufficient.
  Fix: On Debian/Ubuntu: `sudo apt install libvirt-dev`. On RHEL/Fedora: `sudo dnf install libvirt-devel`. Ensure the `libvirtd` service is running.
• gotcha Connecting to hypervisors like `qemu:///system` often requires elevated privileges (e.g., running as root or having your user account in the `libvirt` UNIX group). Connection failures due to permissions are common.
  Fix: Add your user to the `libvirt` group: `sudo usermod -a -G libvirt $USER` (then log out and back in). Alternatively, connect to `qemu:///session` for user-level virtualization or run your script with `sudo` (use with caution).
• deprecated `libvirt-python` versions 4.x and above (released after 2018) have dropped support for Python 2. The current version only supports Python 3.
  Fix: Ensure you are using Python 3.6 or newer. The `libvirt-python` PyPI package specifies `requires_python: >=3.6`.
• gotcha Error handling in `libvirt-python` is done via `libvirt.libvirtError` exceptions. Many operations will raise this exception on failure, requiring robust `try...except` blocks.
  Fix: Wrap `libvirt` calls in `try...except libvirt.libvirtError as e:` to catch and handle API errors gracefully.

Install

• pip install libvirt-python Install with pip

Imports

• libvirt

  import libvirt

  The binding module itself is named `libvirt`.

Quickstart

Connects to the local QEMU/KVM hypervisor, prints its hostname and libvirt version, then closes the connection. This demonstrates basic connection and resource management.

import libvirt
import sys

# Connect to the default QEMU/KVM hypervisor.
# 'qemu:///system' requires appropriate permissions (e.g., user in 'libvirt' group or root).
# For user-session hypervisor, try 'qemu:///session'.
try:
    conn = libvirt.open("qemu:///system")
    if conn is None:
        print('Failed to open connection to qemu:///system', file=sys.stderr)
        sys.exit(1)
except libvirt.libvirtError as e:
    print(f'Failed to open connection: {e}', file=sys.stderr)
    sys.exit(1)

print(f"Successfully connected to libvirt. Hypervisor: {conn.getHostname()}")

# Example: Get and print libvirt version
print(f"Libvirt version: {conn.getVersion()}")

# Always close the connection
conn.close()