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

Writing your own step pays off when conversion is part of a workflow rather than a one-off task.
  • 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

Both start with Markdown and end with a .docx, but they put the work in different places.

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

Install the three packages into a virtual environment. The example below was run with Python 3.13, Python-Markdown 3.11, beautifulsoup4 4.15 and a current python-docx.
bash
python -m venv .venv
source .venv/bin/activate
python -m pip install markdown python-docx beautifulsoup4

On 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

The three steps below are combined into one function at the end of this section.

Step 1 — parse Markdown to HTML

python
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

python
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

python
doc.save("project-notes.docx")

Put the steps together and you get a complete function:

python
# 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

Only the elements the mapper explicitly handles reach the document. This is the behavior of the exact script above.
  • 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 tables extension, but the mapper never reads it, so no Word table is written. Adding one means iterating table rows and calling doc.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

Two areas usually need more work than the basic heading-and-paragraph mapping.

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

If the goal is a single Word file rather than a reusable script, skip the setup.

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

Short answers to the questions that come up when choosing this approach.
Can python-docx convert Markdown by itself?
No. python-docx creates and edits Word files; it does not parse Markdown. You need a Markdown parser such as Python-Markdown or Mistune to produce structured content first, then a mapping step that writes that content into the document.
Why does the example need BeautifulSoup?
Python-Markdown returns an HTML string. BeautifulSoup turns that string into a tree you can walk, so the script can find headings, paragraphs and list items. It is a third dependency, which is why it appears in the install command above. You can replace it with the standard library html.parser if you prefer, but the mapping code becomes longer.
Does the minimal example keep tables, images and math?
No. It only handles h1–h3, paragraphs and list items. Tables and fenced code are parsed by Python-Markdown but skipped by the mapper; inline formatting, links, images and equations are flattened to text. Add explicit handling for each element you need, or use a converter that already does it.
Is Pandoc simpler than writing this script?
For a one-line command, yes. Pandoc reads Markdown and writes DOCX directly, and it handles more of the formatting. See the Pandoc command-line guide for the exact commands and options.
Do I need Python at all for a single file?
No. The online Markdown to Word converter runs in the browser, needs no setup and uses the same document you can preview on the homepage.

Keep exploring