How to Convert Markdown to Word Using Python
Python can write a real .docx file, but it cannot read Markdown on its own. Here is a minimal converter that works, what it leaves out, and when a browser tool is the better choice.
Last updated: November 19, 2026
Looking for a no-code option?
If you just need a Word file, use the Markdown to Word converter. This guide is for when you need conversion inside a Python script or a repeatable build step.
When a Python converter makes sense
- You convert many documents and want the same result every time.
- The conversion runs in a build, test or publishing pipeline where a manual upload would get in the way.
- You need to adjust the mapping, for example to apply your own Word styles.
- The Markdown and the output file should stay on a machine you control.
For a single document, a browser converter is faster and avoids the setup below.
The two main approaches
Markdown → HTML → DOCX
A library such as Python-Markdown turns Markdown into HTML. A second library, python-docx, creates the Word file. You write the mapping between the two. That is more code, but every decision about headings, lists and styles is yours.
Direct Markdown-to-DOCX libraries
Some tools do both steps for you. Pandoc is the most established; from Python it is usually called through pypandoc. It handles far more Markdown by default, but it needs a Pandoc binary available. The Pandoc command-line guide covers that route, including the options and their version differences.
Setup
python -m venv .venv
source .venv/bin/activate
python -m pip install markdown python-docx beautifulsoup4On Windows, activate with .venv\\Scripts\\activate instead of the source line. Python-Markdown parses the source, python-docx writes the .docx, and BeautifulSoup walks the generated HTML.
Example: convert Markdown to DOCX with Python-Markdown and python-docx
Step 1 — parse Markdown to HTML
from markdown import markdown
html = markdown(
"# Project notes\n\n- Draft the outline\n- Review with the team",
extensions=["tables", "fenced_code"],
)The tables and fenced_code extensions are part of Python-Markdown. Without them, pipes and triple backticks stay plain text. The full extension list is in the Python-Markdown documentation.
Step 2 — map HTML blocks to Word paragraphs
from bs4 import BeautifulSoup
from docx import Document
soup = BeautifulSoup(html, "html.parser")
doc = Document()
for node in soup.find_all(["h1", "h2", "h3", "p", "li"], recursive=True):
if node.name in {"h1", "h2", "h3"}:
doc.add_heading(node.get_text(" ", strip=True), int(node.name[1]))
elif node.name == "p":
doc.add_paragraph(node.get_text(" ", strip=True))
elif node.name == "li":
doc.add_paragraph(node.get_text(" ", strip=True), style="List Bullet")Headings become Word heading styles, paragraphs become normal paragraphs, and list items use the built-in List Bullet style. See the python-docx documentation for add_heading, add_paragraph and styles.
Step 3 — save the .docx file
doc.save("project-notes.docx")Put the steps together and you get a complete function:
# pip install markdown python-docx beautifulsoup4
from markdown import markdown
from docx import Document
from bs4 import BeautifulSoup
def convert(markdown_text: str, output_path: str) -> None:
html = markdown(markdown_text, extensions=["tables", "fenced_code"])
soup = BeautifulSoup(html, "html.parser")
doc = Document()
for node in soup.find_all(["h1", "h2", "h3", "p", "li"], recursive=True):
if node.name in {"h1", "h2", "h3"}:
doc.add_heading(node.get_text(" ", strip=True), int(node.name[1]))
elif node.name == "p":
doc.add_paragraph(node.get_text(" ", strip=True))
elif node.name == "li":
doc.add_paragraph(node.get_text(" ", strip=True), style="List Bullet")
doc.save(output_path)
convert("# Project notes\n\n- Draft the outline", "project-notes.docx")Handling headings, lists, tables and code blocks
- Headings: h1, h2 and h3 become Word Heading 1, Heading 2 and Heading 3.
- Paragraphs and lists: paragraphs become body text; list items become flat bullet paragraphs. Nested list hierarchy is not preserved.
- Tables: Python-Markdown builds a table with the
tablesextension, but the mapper never reads it, so no Word table is written. Adding one means iterating table rows and callingdoc.add_table. - Code blocks: fenced code is parsed but skipped in the same way. Insert it as monospaced paragraphs if the document needs it.
- Inline formatting:
get_text()keeps the words but drops bold, italic and link targets.
Deliberately minimal
The script is a starting point, not a full GitHub-Flavored Markdown converter. It does not reproduce task lists, footnotes, math, images or any other element it does not name. The CommonMark specification shows how much Markdown can exist beyond this small subset.
Common limitations
Equations and images
Python-Markdown does not turn LaTeX into Word equations. Math extensions produce MathML or script output in the HTML, and python-docx has no high-level API for an editable Word equation. Getting editable math means building the Word equation markup yourself or using a converter that already supports it. Images are similar: an <img> tag is not embedded by python-docx, so you must download or locate the file and call add_picture with a local path.
Styling and page layout
Document defaults come from python-docx or the template you load. Set styles, section size and margins deliberately if the output is for other people. Word, WPS Office and Google Docs can still lay the same .docx out differently, so open the result and check it before sharing.
When to use an online converter instead
Paste or open your Markdown on the homepage to check the preview, then use the Markdown to Word converter to download an editable .docx. Conversion runs in the browser; the document is not uploaded. Limits still apply: local files up to 150 KB, source text up to 120,000 characters, up to 500 equations and a 25 MB output cap. Remote images are not embedded, and Word layout can differ from the preview. See the MD file guide if you are new to the format.
FAQ
Can python-docx convert Markdown by itself?
Why does the example need BeautifulSoup?
html.parser if you prefer, but the mapping code becomes longer.Does the minimal example keep tables, images and math?
Is Pandoc simpler than writing this script?
Do I need Python at all for a single file?
Keep exploring
Related tools and guides
- Markdown to Word (DOCX)Export Markdown as an editable Word document, including supported equations.
- Markdown Viewer & Live PreviewPaste Markdown or open a local file and preview the formatted result as you type.
- Markdown to Word with PandocCommand-line conversion, useful options and troubleshooting.
- What Is an MD File?What Markdown files contain and how to open, view and convert them.