Install & Compatibility
Where this runs
tested against v0.0.6 · pip install
no network on importno background threads
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
installs and imports cleanly · install 0.0s · import 0.224s · 18.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.198s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QMPClient
✓ from qemu.qmp import QMPClient
ProtocolError
✓ from qemu.qmp import ProtocolError
ExecuteError
✓ from qemu.qmp import ExecuteError
ExecInterruptedError
✓ from qemu.qmp import ExecInterruptedError
✗ from qmp import QMPClient
The original `qmp` package on PyPI is a different, older project. Ensure you use `qemu.qmp` for this library.
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.
import asyncio
import os
from qemu.qmp import QMPClient
async def main():
# Replace '127.0.0.1' and '1234' with your QEMU QMP socket address and port.
# For a UNIX socket, use a path string like '/tmp/qemu-monitor.sock'.
# Ensure QEMU is started with a QMP monitor, e.g.,
# qemu-system-x86_64 -qmp tcp:127.0.0.1:1234,server,nowait -enable-kvm ...
# or
# qemu-system-x86_64 -qmp unix:/tmp/qemu-monitor.sock,server,nowait -enable-kvm ...
qmp_host = os.environ.get('QEMU_QMP_HOST', '127.0.0.1')
qmp_port = int(os.environ.get('QEMU_QMP_PORT', '1234'))
qmp_socket_path = os.environ.get('QEMU_QMP_UNIX_SOCKET', None)
qmp = QMPClient('my_vm_instance')
try:
if qmp_socket_path:
print(f"Connecting to QMP UNIX socket: {qmp_socket_path}")
await qmp.connect(qmp_socket_path)
else:
print(f"Connecting to QMP TCP socket: {qmp_host}:{qmp_port}")
await qmp.connect((qmp_host, qmp_port))
print("Connected to QEMU QMP.")
# Example: Execute 'query-status' command
status_response = await qmp.execute({'execute': 'query-status'})
print(f"QEMU Status: {status_response}")
# Example: Execute 'query-version' command
version_response = await qmp.execute({'execute': 'query-version'})
print(f"QEMU Version: {version_response}")
except Exception as e:
print(f"Error connecting or executing QMP command: {e}")
finally:
if qmp.is_connected():
await qmp.disconnect()
print("Disconnected from QEMU QMP.")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingOlder 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.fixMigrate usage of `device` argument to `id` argument for relevant QMP block device commands.
affects: QEMU >= 2.8
gotchaThe 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.fixAlways use `pip install qemu.qmp` and `from qemu.qmp import ...`.
affects: All versions
gotchaThe 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.fixRegularly check the official QEMU QMP Reference Manual for command deprecations and stability notes. Avoid parsing error details beyond the top-level 'error' key.
affects: All QEMU versions
gotchaSome 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.fixEnsure 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'qemu_qmp'
The qemu-qmp library has not been installed in the current Python environment.
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/qemu-monitor-socket'
The specified Unix domain socket path for the QEMU monitor is incorrect, or QEMU is not running or not configured to create the socket at that location.
fixEnsure QEMU is running with a `-qmp unix:/path/to/socket,server,nowait` argument and the path matches the one used in `QMPClient(path='/path/to/socket')`.
AttributeError: 'NoneType' object has no attribute 'write'
This error occurs when a QMP command is attempted via `client.cmd()` before the `QMPClient` has successfully connected to QEMU via `await client.connect()`.
fixAlways ensure `await client.connect()` has been called and completed successfully before attempting to send any QMP commands.
Upgrade
Version history
0.0.6latest on PyPI · released Mar 31, 2026
Audit
Dependencies
No dependency data recorded yet.