{"record":{"id":"4ac0f0a1a8daee38","repo":"docling-project/docling","slug":"the-python-oxmsg-package-is-required-to-process","errorCode":null,"errorMessage":"The 'python-oxmsg' package is required to process Outlook .msg files. Install it with `pip install 'docling-slim[format-email]'`.","messagePattern":"The 'python-oxmsg' package is required to process Outlook \\.msg files\\. Install it with `pip install 'docling-slim\\[format-email\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/backend/email_backend.py","lineNumber":129,"sourceCode":"        raise TypeError(f\"Unsupported input type: {type(self.path_or_stream)}\")\n\n    @staticmethod\n    def _header_safe(value: str) -> str:\n        # Email header values must be single-line; collapse CR/LF to spaces so a\n        # crafted .msg cannot inject headers and EmailMessage does not reject it.\n        return value.replace(\"\\r\", \" \").replace(\"\\n\", \" \").strip()\n\n    @staticmethod\n    def _msg_to_rfc822_bytes(data: bytes) -> bytes:\n        \"\"\"Project an Outlook ``.msg`` (OLE2/CFB) onto RFC 822 bytes.\n\n        python-oxmsg reads the MAPI message; we assemble a standard\n        ``email.message.EmailMessage`` from it so the ``.msg`` path shares the\n        exact body, HTML, address, and attachment handling used for ``.eml``\n        input.\n        \"\"\"\n        if not _OXMSG_AVAILABLE:\n            raise ImportError(_MSG_INSTALL_HINT) from _OXMSG_IMPORT_ERROR\n\n        message = OxMsgMessage.load(data)\n        email_message = EmailMessage()\n\n        if message.subject:\n            email_message[\"Subject\"] = EmailDocumentBackend._header_safe(\n                message.subject\n            )\n        if message.sender:\n            email_message[\"From\"] = EmailDocumentBackend._header_safe(message.sender)\n\n        # Preserve the To/Cc/Bcc split from the recipient rows so downstream\n        # rendering (which shows only \"To\") matches the .eml behavior.\n        grouped: dict[str, list[str]] = {}\n        for recipient in message.recipients:\n            formatted = formataddr(\n                (recipient.name or \"\", recipient.email_address or \"\")\n            )","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/email_backend.py#L111-L147","documentation":"When the input starts with the Outlook .msg magic bytes, the backend projects it onto RFC 822 via python-oxmsg; if that optional package is missing, _msg_to_rfc822_bytes raises ImportError with the chained original error. mail-parser alone is not enough for .msg files — both packages come with the format-email extra.","triggerScenarios":"Converting an Outlook .msg file (detected by OLE2/CFB magic bytes) in an environment that has mailparser installed but not python-oxmsg, e.g. only `pip install mailparser` was done manually.","commonSituations":"Manually installing the mail dependencies instead of using the extra; environments frozen before .msg support was added; partial dependency lock files.","solutions":["Install the extra: pip install 'docling-slim[format-email]' (brings both mailparser and python-oxmsg)","Or add python-oxmsg explicitly to the environment","Regenerate the lockfile after upgrading Docling so new optional deps are captured"],"exampleFix":"# before\npip install mailparser  # .eml works, .msg raises ImportError\n\n# after\npip install 'docling-slim[format-email]'  # includes mailparser + python-oxmsg","handlingStrategy":"validation","validationCode":"try:\n    import oxmsg  # python-oxmsg\nexcept ImportError:\n    raise RuntimeError(\".msg support needs: pip install 'docling-slim[format-email]'\")","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(msg_path)\nexcept ImportError as exc:\n    if 'python-oxmsg' in str(exc):\n        install_or_skip('docling-slim[format-email]')\n    raise","preventionTips":["Install the full format-email extra rather than individual packages","Probe for python-oxmsg when your pipeline accepts .msg uploads"],"tags":["email","outlook-msg","optional-dependency","importerror"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}