QEMU Machine Protocol (QMP) Client

1.1.0 verified Fri May 01 auth: no python

qmp is a Python client library for the QEMU Machine Protocol (QMP), used to interact with QEMU virtual machines programmatically. The current version is 1.1.0, supported on Python >=3.6. The library is mature but sees infrequent releases.

pip install qmp

Common errors

error ModuleNotFoundError: No module named 'qmp' ↓

cause The library is not installed or the wrong package name is used (e.g., trying `import qemu`).

fix

Run pip install qmp and use from qmp import QEMUMonitorProtocol.

error AttributeError: module 'qmp' has no attribute 'QEMUMonitorProtocol' ↓

cause Trying to import from an old submodule path (e.g., `from qmp.qmp import QEMUMonitorProtocol`).

fix

Use from qmp import QEMUMonitorProtocol directly.

error qmp.QMPError: [Errno 111] Connection refused ↓

cause The QEMU socket path does not exist or QEMU is not running.

fix

Verify the socket path (e.g., check QEMU startup logs) and ensure QEMU is started with '-qmp unix:/tmp/qemu.sock,server,nowait'.

Warnings

breaking Python 3.6 is the minimum required version; Python 2 is not supported. Using with Python <3.6 will cause syntax errors. ↓

fix Use Python >=3.6.

gotcha The connect() method blocks until the connection is established. If QEMU is not ready or the socket path is wrong, it may hang indefinitely. ↓

fix Use connect() with a timeout (e.g., via socket timeout) or implement async connect; qmp does not natively support timeouts.

gotcha Commands expecting a 'return' key in the response may fail if the QMP event is a 'QMP' greeting or an error. Always check the response for success. ↓

fix Always handle 'error' key in response dictionary, or use qmp.command() which raises QMPError on failure (but only for QMP-level errors).

Imports

QEMUMonitorProtocol
wrong
```
from qmp.qmp import QEMUMonitorProtocol
```
correct
```
from qmp import QEMUMonitorProtocol
```
In v1.x, the class is directly exposed at the package level. Old imports from .qmp submodule may fail.

Quickstart

Connect to a running QEMU instance via a Unix socket and execute a QMP command.

from qmp import QEMUMonitorProtocol

# Connect to QEMU over a Unix socket
sock_path = '/tmp/qemu.sock'  # or os.environ.get('QEMU_SOCK', '/tmp/qemu.sock')
try:
    qmp = QEMUMonitorProtocol(sock_path)
    qmp.connect()
    # Send a QMP command
    result = qmp.command('query-status')
    print(result)
finally:
    qmp.close()