mammoth

What it is and what it does

Mammoth is a .docx-to-HTML converter designed to produce clean, semantic markup from Word documents created by Microsoft Word, Google Docs, or LibreOffice. Rather than attempting to replicate visual styling, it interprets document structure—converting a paragraph styled as "Heading 1" to an h1 element, for example—and ignores formatting details like fonts and colors. This approach works well for documents that use styles semantically but may lose fidelity on complex layouts.

The package supports headings, lists, tables, footnotes, images, text formatting (bold, italic, strikethrough, superscript, subscript), links, comments, and custom style mappings. It can be used as a CLI tool or imported as a library. A critical caveat: Mammoth performs no sanitization of source documents, so it must be used carefully with untrusted input. The library also includes text extraction and experimental Markdown output (deprecated in favor of generating HTML first).

Use it for:

• Batch convert Word documents to HTML for web publishing or content management systems.
• Extract semantic structure from styled Word documents for downstream processing or archival.
• Build document pipelines that map custom Word styles to specific HTML classes or elements.
• Preserve document content and structure when migrating from Word to web-based authoring platforms.
• Extract raw text from .docx files while ignoring all formatting and styling.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts Microsoft Word .docx documents to clean HTML or Markdown, using document styles to generate semantic markup rather than attempting to replicate visual formatting.

Yes. Mammoth is actively maintained, has low install friction, carries a permissive license, and solves a well-defined problem—converting .docx to clean HTML using semantic information. It is suitable for most document conversion workflows, but avoid it for untrusted input without additional sanitization and be aware that complex document layouts may not convert perfectly.

Install

mammoth on PyPI

pip install mammoth

uv add mammoth

poetry add mammoth

Installing mammoth

Before you install

Low friction: pure Python wheel with a single runtime dependency (cobble). Active maintenance with a release 5 days ago and 1114 repository stars. Supports Python 3.7 through 3.12.

License in practice

BSD-2-Clause permissive license allows commercial and private use with minimal restrictions, though the package performs no sanitization of untrusted input.

Quickstart

pip install mammoth

import mammoth

with open("document.docx", "rb") as docx_file:
    result = mammoth.convert_to_html(docx_file)
    html = result.value

Input .docx files must be opened in binary mode; conversion works best when documents use semantic styles rather than direct formatting.

Verify before relying

• Whether cobble dependency is lightweight and well-maintained (not disclosed in fact sheet).
• Performance characteristics for large documents or batch conversions.
• Fidelity of table formatting preservation beyond text styling.

Package facts

Evidence: mammoth-1.12.1-py2.py3-none-any.whl

Keywords: docx, word, office, clean, html, markdown, md

Tags

More HTML packages