Incorrent lookup function argument types in libvirt-python API binding

24 Jul 2026

      For some time now I've been developing an app using the libvirt-python
package.

I think I might have spotted an issue with *lookupByUUID* and
*lookupByUUIDString* functions.

First of all, when these functions are passed an argument (machine UUID)
they require it to be in a specific format (16 byte string), however, *there
is virtually no information about this in the documentation* about this - I
managed to find out about this by testing it manually.

Hypothetically - let's take *machine_uuid* of type UUID.

1. This will throw an error:
[...].lookupByUUID(machine_uuid)

2. This will work properly:
[...].lookupByUUID(machine_uuid.*bytes*)

Secondly, in the newest version of libvirt-python (12.5.0) the expected
argument type of function *lookupByUUID* has been changed to *str*. This
causes Python interpreter to highlight all occurrences of lookupByUUID and
show errors:

Argument of type "bytes" cannot be assigned to parameter "uuid" of type
...
"str" in function "lookupByUUID"
"bytes" is not assignable to "str"
Weirdly enough, no actual runtime error is thrown and the lookups work
perfectly fine. However if the argument is actually casted to str the
lookup fails with virDomainLookupByUUIDString() failed error.

More importantly - this change in the argument type makes absolutely no
sense, since now the function lookupByUUID requires exactly the same
argument as lookupByUUIDString - I suppose these functions were supposed to
do different things but now they work exactly the same.

def lookupByUUID(self, uuid: "str") -> "virDomain":
...
"""Try to lookup a domain on the given hypervisor based on its
UUID. """
        ret = libvirtmod.virDomainLookupByUUID(self._o, uuid)
        if ret is None:
            raise libvirtError('virDomainLookupByUUID() failed')
        __tmp = virDomain(self, _obj=ret)
        return __tmp

...
def lookupByUUIDString(self, uuidstr: "str") -> "virDomain":
        """Try to lookup a domain on the given hypervisor based on its UUID
        virDomainFree should be used to free the resources after the
        domain object is no longer needed. """
        ret = libvirtmod.virDomainLookupByUUIDString(self._o, uuidstr)
        if ret is None:
            raise libvirtError('virDomainLookupByUUIDString() failed')
        __tmp = virDomain(self, _obj=ret)
        return __tmp
Best regards, Krzysztoff