zylon-ai/private-gpt · error · ImportError

MarkItDown reader dependencies are not installed. Install wi

Error message

MarkItDown reader dependencies are not installed. Install with `uv sync --inexact --extra ingest-markitdown`.

What it means

Raised as ImportError by MarkItDownReaderFactory.create_reader when the lazy import of private_gpt.components.readers.markitdown.markitdown_reader fails. Reader dependencies are optional extras in this project: the markitdown module imports the markitdown package, which is only installed with the 'ingest-markitdown' extra. The message includes the exact uv sync command; the original ImportError is chained so the truly missing module is visible via __cause__.

Source

Thrown at private_gpt/components/readers/factories/markitdown.py:15

from private_gpt.components.readers.base_reader import IngestionReader
from private_gpt.components.readers.factories.base import ReaderFactory
from private_gpt.utils.dependencies import format_missing_dependency_message


class MarkItDownReaderFactory(ReaderFactory):
    def create_reader(self, extension: str | None = None) -> IngestionReader:
        del extension

        try:
            from private_gpt.components.readers.markitdown.markitdown_reader import (
                MarkItDownReader,
            )
        except ImportError as e:
            raise ImportError(
                format_missing_dependency_message(
                    "MarkItDown reader",
                    extras="ingest-markitdown",
                )
            ) from e

        return MarkItDownReader()

View on GitHub (pinned to 4a030776a3)

Solutions

Run the exact command from the message: uv sync --inexact --extra ingest-markitdown (the --inexact flag keeps your other installed deps).
If it still fails after installing, inspect e.__cause__ to see which inner module is missing and add that dependency.
Alternatively switch the reader selection to 'docling' if you cannot add the extra to this environment.
For Docker deployments, add the extra to the image build (uv sync --inexact --extra ingest-markitdown in the Dockerfile).

Example fix

# before (fails at runtime)
reader = registry.get_factory("markitdown").create_reader()

# fix the environment instead
# uv sync --inexact --extra ingest-markitdown

Defensive patterns

Strategy: validation

Validate before calling

def markitdown_available() -> bool:
    try:
        import markitdown  # noqa: F401
        return True
    except ImportError:
        return False

if not markitdown_available():
    raise SystemExit("Install first: uv sync --inexact --extra ingest-markitdown")

Type guard

def markitdown_available() -> bool:
    try:
        import markitdown  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    reader = registry.get_factory("markitdown").create_reader()
except ImportError as e:
    if "ingest-markitdown" in str(e):
        raise SystemExit("Run: uv sync --inexact --extra ingest-markitdown") from e
    raise

Prevention

Install the extra in the same environment/interpreter that runs the app (uv run guarantees it).
Add import availability checks to deployment smoke tests for every reader you select in settings.

When it happens

Trigger: Configuring ingestion to use the 'markitdown' reader (get_factory('markitdown').create_reader()) in an environment installed without the ingest-markitdown extra, or with a broken/partial install where the markitdown package itself is missing an optional sub-dependency it dynamically imports.

Common situations: Fresh clone installed as `uv sync` without extras, then selecting markitdown in settings; Docker images trimmed to default extras; a markitdown release that made a format handler an optional dependency, so the package imports but a transitive import fails.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/93fe9db2f1bd2d2a. Report an issue: GitHub.