{"id":6844,"library":"qemu-qmp","title":"QEMU Monitor Protocol Library","description":"qemu.qmp is a Python library, built on asyncio, for interacting with QEMU emulators via the QEMU Monitor Protocol (QMP). It enables sending QMP messages to control and query QEMU instances, including the QEMU Guest Agent (QGA) and QEMU Storage Daemon (QSD). The library currently stands at version 0.0.6 and has a release cadence tied to the QEMU project's development, as it was originally split from the QEMU source tree.","status":"active","version":"0.0.6","language":"en","source_language":"en","source_url":"https://github.com/qemu/qemu/tree/master/python/qemu/qmp","tags":["qemu","qmp","asyncio","virtualization","emulator"],"install":[{"cmd":"pip install qemu.qmp","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"QMPClient","correct":"from qemu.qmp import QMPClient"},{"symbol":"ProtocolError","correct":"from qemu.qmp import ProtocolError"},{"symbol":"ExecuteError","correct":"from qemu.qmp import ExecuteError"},{"note":"The original `qmp` package on PyPI is a different, older project. Ensure you use `qemu.qmp` for this library.","wrong":"from qmp import QMPClient","symbol":"ExecInterruptedError","correct":"from qemu.qmp import ExecInterruptedError"}],"quickstart":{"code":"import asyncio\nimport os\nfrom qemu.qmp import QMPClient\n\nasync def main():\n    # Replace '127.0.0.1' and '1234' with your QEMU QMP socket address and port.\n    # For a UNIX socket, use a path string like '/tmp/qemu-monitor.sock'.\n    # Ensure QEMU is started with a QMP monitor, e.g., \n    # qemu-system-x86_64 -qmp tcp:127.0.0.1:1234,server,nowait -enable-kvm ...\n    # or\n    # qemu-system-x86_64 -qmp unix:/tmp/qemu-monitor.sock,server,nowait -enable-kvm ...\n    qmp_host = os.environ.get('QEMU_QMP_HOST', '127.0.0.1')\n    qmp_port = int(os.environ.get('QEMU_QMP_PORT', '1234'))\n    qmp_socket_path = os.environ.get('QEMU_QMP_UNIX_SOCKET', None)\n\n    qmp = QMPClient('my_vm_instance')\n\n    try:\n        if qmp_socket_path:\n            print(f\"Connecting to QMP UNIX socket: {qmp_socket_path}\")\n            await qmp.connect(qmp_socket_path)\n        else:\n            print(f\"Connecting to QMP TCP socket: {qmp_host}:{qmp_port}\")\n            await qmp.connect((qmp_host, qmp_port))\n\n        print(\"Connected to QEMU QMP.\")\n\n        # Example: Execute 'query-status' command\n        status_response = await qmp.execute({'execute': 'query-status'})\n        print(f\"QEMU Status: {status_response}\")\n\n        # Example: Execute 'query-version' command\n        version_response = await qmp.execute({'execute': 'query-version'})\n        print(f\"QEMU Version: {version_response}\")\n\n    except Exception as e:\n        print(f\"Error connecting or executing QMP command: {e}\")\n    finally:\n        if qmp.is_connected():\n            await qmp.disconnect()\n            print(\"Disconnected from QEMU QMP.\")\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to connect to a running QEMU instance via its QMP interface (either TCP or UNIX socket) and execute a simple 'query-status' and 'query-version' command. Remember to start your QEMU VM with a QMP monitor enabled (e.g., `-qmp tcp:127.0.0.1:1234,server,nowait`). Environment variables `QEMU_QMP_HOST`, `QEMU_QMP_PORT`, or `QEMU_QMP_UNIX_SOCKET` can be used to configure the connection."},"warnings":[{"fix":"Migrate usage of `device` argument to `id` argument for relevant QMP block device commands.","message":"Older QMP commands, particularly those using `device` argument for `blockdev-open-tray`, `blockdev-close-tray`, `eject`, `blockdev-change-medium`, and `block_set_io_throttle`, are deprecated since QEMU 2.8. They should be replaced with the `id` argument. Using deprecated commands with newer QEMU versions may lead to unexpected behavior or errors.","severity":"breaking","affected_versions":"QEMU >= 2.8"},{"fix":"Always use `pip install qemu.qmp` and `from qemu.qmp import ...`.","message":"The PyPI package `qmp` (pypi.org/project/qmp) is an older, distinct project. This library is `qemu.qmp` (pypi.org/project/qemu.qmp). Ensure you are installing and importing from the correct package (`qemu.qmp`) to avoid using an unmaintained or incompatible library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly check the official QEMU QMP Reference Manual for command deprecations and stability notes. Avoid parsing error details beyond the top-level 'error' key.","message":"The QMP command set is subject to a deprecation policy in QEMU. Commands may have ill-defined semantics, and applications should not rely on undocumented behavior, specific error classes, or data beyond the 'error' key. Always consult the QEMU QMP Reference Manual for stability considerations.","severity":"gotcha","affected_versions":"All QEMU versions"},{"fix":"Ensure the QEMU Guest Agent is installed and enabled in the guest for guest-specific queries. Verify QEMU version and its capabilities for commands. Use `qmp_capabilities` to query supported commands.","message":"Some QMP commands, particularly for querying specific guest details (e.g., `guest-get-cpustats`, `query-memory-devices`), may return 'CommandNotFound' or empty results if the QEMU Guest Agent (QGA) is not installed and running within the guest, or if the QEMU version does not support the command or capability.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}