zylon-ai/private-gpt · error · ImportError

HTML reader dependencies are not installed. Install with `uv

Error message

HTML reader dependencies are not installed. Install with `uv sync --inexact --extra ingest-markup`.

What it means

Raised as ImportError by _html_reader() in factories/text.py when the lazy import of HtmlReader fails because its HTML-parsing dependencies (e.g., beautifulsoup4/lxml-style libs) are not installed. These live in the 'ingest-markup' extra, and the message includes the precise uv sync command with --inexact to avoid disturbing other installed packages. The original ImportError is chained as __cause__.

Source

Thrown at private_gpt/components/readers/factories/text.py:40

        from private_gpt.components.readers.text.email_reader import (
            EmailTextReader,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Email reader",
            )
        ) from e
    return EmailTextReader()


def _html_reader() -> IngestionReader:
    try:
        from private_gpt.components.readers.text.html_reader import (
            HtmlReader,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "HTML reader",
                extras="ingest-markup",
            )
        ) from e
    return HtmlReader()


def _text_reader() -> IngestionReader:
    try:
        from private_gpt.components.readers.text.text_reader import (
            TextReader,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Text reader",
            )

View on GitHub (pinned to 4a030776a3)

Solutions

Run the command from the message: uv sync --inexact --extra ingest-markup.
If already installed, inspect e.__cause__ — for lxml issues install the system libraries (libxml2-dev/libxslt-dev) or re-install the wheel so it rebuilds.
Re-sync after any Python version change: uv sync (venv binaries like lxml are version-specific).
Alternatively route HTML through the 'docling' reader if you cannot add the extra locally.

Example fix

# fix the environment
# uv sync --inexact --extra ingest-markup
# verify
# uv run python -c "from private_gpt.components.readers.text.html_reader import HtmlReader"

Defensive patterns

Strategy: validation

Validate before calling

def html_deps_available() -> bool:
    try:
        import bs4  # and/or lxml, per the reader's imports
        return True
    except ImportError:
        return False

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

Type guard

def html_deps_available() -> bool:
    try:
        import bs4  # noqa: F401
        import lxml  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    reader = _html_reader()
except ImportError as e:
    if "ingest-markup" in str(e):
        raise SystemExit("Run: uv sync --inexact --extra ingest-markup") from e
    # installed but broken (e.g., lxml system libs): surface the cause
    raise RuntimeError(f"HTML deps present but unimportable: {e.__cause__!r}") from e

Prevention

Install the ingest-markup extra in every environment that ingests HTML.
After OS upgrades, re-install lxml so its binary wheel matches system libxml2.
Re-sync the venv after changing Python versions — binary packages do not carry over.

When it happens

Trigger: Ingesting HTML files through the 'text' reader without the ingest-markup extra installed — the lazy import inside _html_reader fails and is re-raised with install instructions. Can also fire when lxml/bs4 binary wheels are broken on exotic platforms even though the extra was installed.

Common situations: Default install without extras followed by ingesting .html files; slim Docker images; lxml failing to import due to a missing system libxml2 after an OS upgrade; partial venv state after switching Python versions without re-syncing.

Related errors

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