docling-project/docling · error · ImportError

The 'mail-parser' package is required to process email files

Error message

The 'mail-parser' package is required to process email files. Install it with `pip install 'docling-slim[format-email]'`.

What it means

EmailDocumentBackend.__init__ raises ImportError before super().__init__() when the optional mail-parser dependency is not installed, with the chained original import error preserved. Docling ships email support as an optional extra, so importing the backend without the package installed is a supported but actionable failure.

Source

Thrown at docling/backend/email_backend.py:81

_MSG_INSTALL_HINT = (
    "The 'python-oxmsg' package is required to process Outlook .msg files. "
    "Install it with `pip install 'docling-slim[format-email]'`."
)


class EmailDocumentBackend(DeclarativeDocumentBackend):
    def __init__(
        self,
        in_doc: InputDocument,
        path_or_stream: BytesIO | Path,
        options: EmailBackendOptions | None = None,
    ):
        # Raised before super().__init__() so a missing optional dependency
        # gives an actionable message rather than a NameError when mailparser
        # is dereferenced below.
        if not _MAILPARSER_AVAILABLE:
            raise ImportError(_INSTALL_HINT) from _MAILPARSER_IMPORT_ERROR
        if options is None:
            options = EmailBackendOptions()
        super().__init__(in_doc, path_or_stream, options)

        self.options: EmailBackendOptions = options
        self.valid = False
        self.is_msg = False
        self.mail: mailparser.MailParser | None = None

        try:
            raw = self._read_bytes()
            self.is_msg = raw.startswith(_MSG_MAGIC)
            if self.is_msg:
                raw = self._msg_to_rfc822_bytes(raw)
            self.mail = mailparser.parse_from_bytes(raw)

            self.valid = self.mail is not None
        except ImportError:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install the extra: pip install 'docling-slim[format-email]'
Or install the full package: pip install docling
Pin the extra in requirements.txt/pyproject so CI and Docker rebuilds keep it

Example fix

# before
pip install docling-slim

# after
pip install 'docling-slim[format-email]'

Defensive patterns

Strategy: validation

Validate before calling

try:
    import mailparser  # noqa: F401
except ImportError:
    raise RuntimeError("Install: pip install 'docling-slim[format-email]'")

Try / catch

try:
    result = converter.convert(src)
except ImportError as exc:
    if 'mail-parser' in str(exc):
        install_or_skip('docling-slim[format-email]')
    raise

Prevention

Declare format extras explicitly in pyproject/requirements
Add a startup dependency probe for every format your service accepts

When it happens

Trigger: Constructing EmailDocumentBackend (or converting an .eml file) in an environment where `import mailparser` failed — e.g. docling-slim installed without the format-email extra.

Common situations: Installing docling-slim instead of full docling; slimming a Docker image and dropping extras; upgrading Docling in a venv where the extra was never re-added.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/e6d441a7e0d2a035. Report an issue: GitHub.