ocrmypdf/OCRmyPDF · error · ImportError

Could not load plugin from {plugin_path}

Error message

Could not load plugin from {plugin_path}

What it means

Raised by the plugin manager when a plugin given as a .py file path cannot be imported — importlib.util.spec_from_file_location returns no spec/loader, meaning the file doesn't exist, isn't a loadable Python module, or the path is wrong.

Source

Thrown at src/ocrmypdf/_plugin_manager.py:111

            for module_info in sorted(
                pkgutil.iter_modules(ocrmypdf.builtin_plugins.__path__)
            ):
                name = f'ocrmypdf.builtin_plugins.{module_info.name}'
                module = importlib.import_module(name)
                self._pm.register(module)

        # 2. Register setuptools plugins
        self._pm.load_setuptools_entrypoints('ocrmypdf')

        # 3. Register plugins specified on command line
        for plugin in self._plugins:
            if isinstance(plugin, Path) or plugin.endswith('.py'):
                # Import by filename
                plugin_path = Path(plugin)
                module_name = plugin_path.stem
                spec = importlib.util.spec_from_file_location(module_name, plugin_path)
                if spec is None or spec.loader is None:
                    raise ImportError(f'Could not load plugin from {plugin_path}')
                module = importlib.util.module_from_spec(spec)
                sys.modules[module_name] = module
                spec.loader.exec_module(module)
            else:
                # Import by dotted module name
                module = importlib.import_module(plugin)
            self._pm.register(module)

    # =========================================================================
    # Type-safe hook methods
    # =========================================================================

    # --- firstresult hooks ---

    def get_logging_console(self) -> Handler | None:
        """Returns a custom logging handler for progress bar compatibility."""
        return self._pm.hook.get_logging_console()

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Verify the plugin path exists and is absolute
2. Check the file is valid Python (python -c 'import ast; ast.parse(open("plugin.py").read())')
3. Use a dotted module name instead if the plugin is installed as a package

Example fix

# before
ocrmypdf --plugin plugins/myplug.py in.pdf out.pdf
# after
ocrmypdf --plugin /abs/path/plugins/myplugin.py in.pdf out.pdf

from pathlib import Path
p = Path(plugin_arg)
if p.suffix == '.py' and not (p.is_file() and p.read_text().count('') >= 0):
    raise SystemExit(f'plugin not found: {p.resolve()}')

catch ImportError, log plugin path, skip plugin and continue if optional

When it happens

Trigger: Passing --plugin some_path.py that doesn't exist or isn't valid Python; happens during OcrMyPDF plugin setup at initialization.

Common situations: Typo in the plugin path, moved/renamed plugin file, plugin with syntax errors so severe the spec fails, or relative path resolved from the wrong working directory.

Related errors

• --redo-ocr (or --mode redo) is not currently compatible with
• Since you specified `--output-type none`, the output file {s
• Input file is an image, but the resolution (DPI) is not cred
• Input file is an image, but has no resolution (DPI) in its m
• The input image has an alpha channel. Remove the alpha chann

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/c1f998aef271fb85. Report an issue: GitHub.