QPluginLoader::unload() returns false after deleting the plugin instance

Answer

The call to QPluginLoader::unload() fails because something created from the plugin’s binary is still alive or still referenced by the Qt type system. Until every such reference is released, the underlying OS will not free the library (on Windows the DLL remains locked).

Confirmed facts

• The documentation states that unloading is safe only when no objects created from the plugin remain alive.
• Any instance returned by QPluginLoader::instance() and all of its child QObjects keep the library mapped.
• Objects allocated with new inside the plugin code also count, even if they are not parented to the root instance.
• Custom type registrations via qRegisterMetaType() or QML type registration create global entries in Qt’s type system that hold a reference to the plugin’s code segment; these registrations are not automatically undone when the instance is deleted.
• On Windows the OS maintains a reference count on the DLL; any remaining static data, active threads, or handles originating from the plugin will block FreeLibrary, causing unload() to return false.
• The return value of unload() is opaque: it only tells whether the platform call succeeded, not which references remain.

Likely explanation for your case

You delete the root instance with deleteLater() and process events, but the plugin also registers custom metatypes and exposes a singleton‑like object. Unless those metatype registrations are avoided or the singleton is destroyed and its references cleared, the type system still holds a reference to the plugin’s code, preventing unload.

Steps to make unload succeed (if possible)

1. Ensure the root instance obtained from instance() has no parent and is deleted.
2. Process the event loop (QCoreApplication::processEvents() or run the event loop) until the instance’s destroyed() signal is emitted.
3. Verify that no other objects allocated from the plugin remain (check for any new‑ed objects you created manually).
4. Avoid registering custom metatypes or QML types from the plugin if you intend to hot‑reload; if registration is required, you must accept that the plugin cannot be unloaded without restarting the application.
5. After the above, call loader->unload(); it should return true on platforms where the library can be freed.

Missing diagnostic detail

If you have registered any custom metatypes or QML types from the plugin, the only reliable way to achieve near‑zero‑downtime updates is to use a process‑level handover (e.g., QLocalServer/QLocalSocket) rather than relying on QPluginLoader::unload(). Let me know whether your plugin performs such registrations so I can confirm if the handover pattern is needed.