opendataloader-project/opendataloader-pdf · error · ImportError

Missing dependencies: {', '.join(missing)}. Install with: pi

Error message

Missing dependencies: {', '.join(missing)}. Install with: pip install opendataloader-pdf[hybrid]

What it means

ImportError raised by _check_dependencies at hybrid server startup when one or more of uvicorn, fastapi, or docling cannot be imported. These are optional dependencies declared under the [hybrid] extra, not in the base install, so the server refuses to start (rather than failing later on the first request) and names the missing packages plus the install command.

Source

Thrown at python/opendataloader-pdf/src/opendataloader_pdf/hybrid_server.py:301

def _check_dependencies():
    """Check if hybrid dependencies are installed."""
    missing = []
    try:
        import uvicorn  # noqa: F401
    except ImportError:
        missing.append("uvicorn")
    try:
        import fastapi  # noqa: F401
    except ImportError:
        missing.append("fastapi")
    try:
        import docling  # noqa: F401
    except ImportError:
        missing.append("docling")

    if missing:
        raise ImportError(
            f"Missing dependencies: {', '.join(missing)}. "
            "Install with: pip install opendataloader-pdf[hybrid]"
        )


def _check_ocr_engine_available(engine_kind: str) -> tuple[bool, str]:
    """Probe runtime prerequisites for the selected OCR engine.

    Called at startup so a missing binary or Python package surfaces before the
    first request rather than mid-conversion. Returns (ok, error_message).

    `easyocr` ships with the `[hybrid]` extra and `auto` defers engine choice to
    docling at conversion time, so both are treated as always available. Other
    engines pull in extra system or Python dependencies that are not declared
    in pyproject and must be installed by the user.
    """
    import importlib.util
    import shutil

View on GitHub (pinned to a7789b8e77)

Solutions

  1. Install the hybrid extra: pip install 'opendataloader-pdf[hybrid]'.
  2. If only some packages are missing, install them directly: pip install uvicorn fastapi docling (or the subset named in the message).
  3. Recreate the venv from the project's lockfile/constraints that include the hybrid extras.
  4. Verify with python -c 'import uvicorn, fastapi, docling' before starting the server.

Example fix

# before: base install, hybrid deps missing
$ pip install opendataloader-pdf
$ python -m opendataloader_pdf.hybrid_server  # -> ImportError: Missing dependencies: uvicorn, fastapi, docling
# after: install the extra
$ pip install 'opendataloader-pdf[hybrid]'
Defensive patterns

Strategy: validation

Validate before calling

def hybrid_deps_ok() -> bool:
    import importlib.util
    return all(importlib.util.find_spec(m) is not None for m in ("uvicorn", "fastapi", "docling"))

Type guard

def is_missing_hybrid_deps(exc: ImportError) -> bool:
    return isinstance(exc, ImportError) and "Missing dependencies" in str(exc)

Try / catch

try:
    from opendataloader_pdf.hybrid_server import main
    main()
except ImportError as e:
    if "Missing dependencies" in str(e):
        print("Install the extra: pip install 'opendataloader-pdf[hybrid]'")
    raise

Prevention

When it happens

Trigger: Starting the hybrid server (python -m opendataloader_pdf.hybrid_server or its CLI) in an environment where opendataloader-pdf was installed WITHOUT the [hybrid] extra, so uvicorn/fastapi/docling are absent.

Common situations: User ran pip install opendataloader-pdf (base) then tried to launch the hybrid backend. A venv was created from a constraints file that omitted the hybrid deps. A dependency resolver downgraded/removed a transitive package.

Related errors

AI-assisted analysis of opendataloader-project/opendataloader-pdf@a7789b8e77 (2026-08-14). Data as JSON: /api/errors/db4967f73f2f987f. Report an issue: GitHub.