mammoth

library1.12.1pypypi✓ verified 24d ago

Mammoth is an open-source Python library designed to convert Microsoft Word `.docx` documents into clean and semantic HTML or Markdown. It focuses on preserving the semantic structure of the document (e.g., headings, lists, tables) rather than attempting to replicate exact visual formatting. The current version is 1.12.0. The library has a steady release cadence, with updates addressing features and maintenance.

serialization data

pip install mammoth

github ↗package ↗

INSTALL

IMPORT

SIG · MAMMOTH

mammoth

serializationpythonv1.12.1

Install

1.6s avg

Import

303ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.12.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.328s · 18.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.278s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

convert_to_html

✓ from mammoth import convert_to_html

✗ import mammoth

convert_to_markdown

✓ from mammoth import convert_to_markdown

✗ import mammoth

convert

✓ from mammoth import convert

✗ import mammoth

This quickstart demonstrates how to convert a `.docx` file to HTML using `mammoth.convert_to_html`. It also shows how to access any messages (warnings or errors) generated during the conversion process. The input file must be opened in binary read mode (`'rb'`). For this example, a dummy `.docx` file is created using the `python-docx` library.

import mammoth # Create a dummy docx file for demonstration from docx import Document document = Document() document.add_heading('My Document Title', level=1) document.add_paragraph('This is a paragraph with some **bold** and *italic* text.') document.add_paragraph('A second paragraph.') document.save('document.docx') # Convert docx to HTML with open('document.docx', 'rb') as docx_file: result = mammoth.convert_to_html(docx_file) html = result.value messages = result.messages print('Generated HTML:') print(html) if messages: print('\nMessages during conversion:') for message in messages: print(message) # Clean up the dummy file import os os.remove('document.docx')

Debug

Known issues

gotchaMammoth prioritizes semantic conversion over exact visual fidelity. It converts styles like 'Heading 1' to `<h1>` elements, ignoring precise font sizes or colors. Users expecting a pixel-perfect rendition of their Word document may be disappointed by the 'clean' HTML output.

fix

Understand Mammoth's design philosophy: it converts semantic meaning. Use custom style mappings to fine-tune HTML output based on your DOCX styles, focusing on structure rather than visual appearance. Review the generated HTML to ensure it meets your structural requirements.

affects: All versions

breakingMarkdown support is deprecated. The `convert_to_markdown` function still exists but is discouraged. Future versions may remove or significantly change this functionality. Generating HTML and then using a separate library for HTML to Markdown conversion is recommended for better results.

fix

Migrate to converting DOCX to HTML using `mammoth.convert_to_html` and then use a dedicated HTML-to-Markdown conversion library if Markdown is required.

affects: >=1.11.0

breakingMammoth performs no sanitization of the source `.docx` document. Converting documents from untrusted users can introduce security vulnerabilities, such as `javascript:` links in the output HTML.

fix

Always sanitize the HTML output generated by Mammoth, especially if the source documents originate from untrusted users. Implement a robust HTML sanitization library (e.g., `Bleach`) after conversion to remove potentially malicious content.

affects: All versions

gotchaWMF images are not handled by default. If your `.docx` documents contain WMF images, they will not be correctly converted or embedded in the output HTML.

fix

Convert WMF images to a supported format (e.g., PNG) before conversion, or implement a custom image converter using `mammoth.images.img_element` that leverages external tools like LibreOffice as demonstrated in the Mammoth recipes.

affects: All versions

gotchaCustom style mappings using `p[style-name='...'] => ...:fresh` can lead to unexpected HTML structures if not fully understood. The `:fresh` option forces a new HTML element, rather than appending content to an existing one, which can be critical for layout.

fix

Carefully test custom style mappings, especially when using `:fresh`. Understand when you want content appended to an existing HTML element versus when a new element should be created. Refer to the official documentation for advanced style mapping syntax.

affects: All versions

Upgrade

Version history

1.12.1latest on PyPI · released Aug 9, 2026

Audit

Dependencies

cobblerequiredInternal dependency for document processing.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/mwilliamson/python-mammoth ↗

packagehttps://pypi.org/project/mammoth/ ↗