Install & Compatibility
Where this runs
tested against v0.11.0 · 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.132s · 18.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.119s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Plugin
✓ from pluginlib import Plugin
PluginLoader
✓ from pluginlib import PluginLoader
This quickstart demonstrates how to define a simple plugin and use Pluginlib's `PluginLoader` to discover and instantiate it. It creates a temporary file structure to make the example self-contained and runnable, then cleans it up. The loader searches a specified path for modules, identifies classes inheriting from `pluginlib.Plugin`, and allows you to interact with their instances.
import os
import tempfile
import shutil
from pluginlib import Plugin, PluginLoader
# --- Setup: Create a temporary directory and a dummy plugin file ---
# This simulates having a 'plugins' directory with 'my_plugin.py'
temp_dir = tempfile.TemporaryDirectory()
plugin_root_dir = temp_dir.name
plugin_dir_path = os.path.join(plugin_root_dir, "plugins")
os.makedirs(plugin_dir_path, exist_ok=True)
plugin_file_path = os.path.join(plugin_dir_path, "my_plugin.py")
with open(plugin_file_path, "w") as f:
f.write("""
from pluginlib import Plugin
class MyPlugin(Plugin):
version = "1.0.0"
def execute(self) -> str:
return "Hello from MyPlugin!"
""")
# --- End Setup ---
try:
# Initialize the PluginLoader to search in our temporary 'plugins' directory
# We specify the exact plugin module name and its base class
with PluginLoader(
[plugin_root_dir], # Search path includes the root of our plugins dir
plugin_name="my_plugin", # The name of the module (my_plugin.py)
plugin_class="Plugin" # The base class for our plugins
) as loader:
# Access the loaded plugins. 'plugins' is a nested dictionary:
# {module_name: {plugin_class_name: instance}}
loaded_plugins = loader.plugins
if "my_plugin" in loaded_plugins and "MyPlugin" in loaded_plugins["my_plugin"]:
my_plugin_instance = loaded_plugins["my_plugin"]["MyPlugin"]
result = my_plugin_instance.execute()
print(f"Successfully loaded and executed plugin: {result}")
print(f"Plugin version: {my_plugin_instance.version}")
else:
print("Error: MyPlugin could not be found or loaded.")
finally:
# --- Teardown: Clean up the temporary directory ---
temp_dir.cleanup()
# --- End Teardown ---
Debug
Known issues
breakingPluginlib dropped support for Python 2.6 and older Python 3 versions.fixEnsure your project uses Python 3.6+ to be compatible with recent versions of pluginlib.
affects: 0.9.0 and later
gotchaWhen loading plugins from namespace packages, pluginlib explicitly states that these packages are NOT searched recursively for imports. This means sub-modules within a namespace package won't be automatically discovered.fixAvoid deep nesting of plugins within namespace packages if you expect recursive discovery, or ensure each plugin module is directly discoverable by the specified paths.
affects: 0.10.0 and later
breakingThe return type of `PluginLoader.plugins_all()` at its lowest level changed from a regular dictionary to an `OrderedDict`. Code relying on `dict` iteration order or direct indexing might be affected.fixUpdate code that processes the output of `plugins_all` to correctly handle `OrderedDict` or convert it if strict dictionary behavior is required.
affects: 0.7.0 and later
gotchaIf an abstract method in a base `Plugin` class is defined as a coroutine (async), any overriding method in a child plugin class must also be defined as a coroutine.fixEnsure consistent `async` definitions between parent abstract methods and child implementations to avoid `TypeError` or unexpected behavior.
affects: 0.7.0 and later
Upgrade
Version history
0.11.0latest on PyPI · released Apr 26, 2026
Audit
Dependencies
packagingrequiredUsed for robust version parsing (introduced in 0.10.0).
importlib-metadataoptionalBackport for importlib.metadata functionality on Python versions < 3.10, used for querying entrypoints.