{"id":8276,"library":"libvirt-python","title":"libvirt-python binding for Libvirt API","description":"The `libvirt-python` library provides a Pythonic binding to the C API of libvirt, the open-source virtualization management library. It allows Python applications to manage virtual machines, storage, and networking on various hypervisors like KVM, QEMU, and Xen. Currently at version 12.2.0, it generally tracks the libvirt C library's release cycle, typically seeing multiple updates per year.","status":"active","version":"12.2.0","language":"en","source_language":"en","source_url":"https://github.com/libvirt/libvirt-python","tags":["virtualization","KVM","libvirt","VM management","hypervisor","qemu"],"install":[{"cmd":"pip install libvirt-python","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The binding module itself is named `libvirt`.","symbol":"libvirt","correct":"import libvirt"}],"quickstart":{"code":"import libvirt\nimport sys\n\n# Connect to the default QEMU/KVM hypervisor.\n# 'qemu:///system' requires appropriate permissions (e.g., user in 'libvirt' group or root).\n# For user-session hypervisor, try 'qemu:///session'.\ntry:\n    conn = libvirt.open(\"qemu:///system\")\n    if conn is None:\n        print('Failed to open connection to qemu:///system', file=sys.stderr)\n        sys.exit(1)\nexcept libvirt.libvirtError as e:\n    print(f'Failed to open connection: {e}', file=sys.stderr)\n    sys.exit(1)\n\nprint(f\"Successfully connected to libvirt. Hypervisor: {conn.getHostname()}\")\n\n# Example: Get and print libvirt version\nprint(f\"Libvirt version: {conn.getVersion()}\")\n\n# Always close the connection\nconn.close()","lang":"python","description":"Connects to the local QEMU/KVM hypervisor, prints its hostname and libvirt version, then closes the connection. This demonstrates basic connection and resource management."},"warnings":[{"fix":"On Debian/Ubuntu: `sudo apt install libvirt-dev`. On RHEL/Fedora: `sudo dnf install libvirt-devel`. Ensure the `libvirtd` service is running.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are using Python 3.6 or newer. The `libvirt-python` PyPI package specifies `requires_python: >=3.6`.","message":"`libvirt-python` versions 4.x and above (released after 2018) have dropped support for Python 2. The current version only supports Python 3.","severity":"deprecated","affected_versions":"<=3.x for Python 2 support; >=4.0 for Python 3 only"},{"fix":"Wrap `libvirt` calls in `try...except libvirt.libvirtError as e:` to catch and handle API errors gracefully.","message":"Error handling in `libvirt-python` is done via `libvirt.libvirtError` exceptions. Many operations will raise this exception on failure, requiring robust `try...except` blocks.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `libvirt-python` package is not installed, or the underlying `libvirt` C library is missing or cannot be found by the Python binding.","error":"ImportError: No module named 'libvirt'"},{"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).","cause":"The libvirtd daemon is not running, the connection URI is incorrect, or required permissions are not met.","error":"libvirt.libvirtError: Failed to connect to socket"},{"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.","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`.","error":"libvirt.libvirtError: internal error: Client and server are in different primary groups"}]}