---
id: mammoth
version: "1.12.1"
license: BSD-2-Clause
license_treatment: permissive
maintenance: active
---

# mammoth — Convert Word documents from docx to simple and clean HTML and Markdown

License: permissive · Maintenance: active · Downloads: 16.1M/mo

## 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 above — 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

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

- License: BSD-2-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 16.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

docx to html converter, word document to html, convert docx files, docx html conversion, word to html python, document format conversion, semantic html from docx, document-conversion, cli-tool

[View on SkillFed](https://skillfed.io/packages/mammoth) · [View on PyPI](https://pypi.org/project/mammoth/)