How to Convert Markdown to Word Using Pandoc

Pandoc reads Markdown and writes a real .docx file. These are the commands and options that work, what each one changes, and the problems that come up most often.

Last updated: November 19, 2026

Looking for a no-install option?

Use the Markdown to Word converter if you want a Word file without setting up a command-line tool. This guide is for repeatable, scriptable conversion.

What Pandoc does

Pandoc is a document converter with a Markdown reader and a Word writer.

You give it a Markdown file and an output name; it writes a standard .docx. Headings, paragraphs, tables and equations are written as Word structures rather than as a picture of the page. That makes the result editable in Word and usable in other Word-compatible applications.

It converts structure, not visual layout. Page size, margins and exact spacing come from Pandoc's defaults or from a reference document, and Word still controls final pagination. The Pandoc User's Guide documents the readers, writers and options in detail.

Install Pandoc

Installers and package-manager commands are listed on the official installation page.

macOS / Windows / Linux package managers

bash
# macOS (Homebrew)
brew install pandoc

# Windows (winget)
winget install --source winget --exact --id JohnMacFarlane.Pandoc

# Debian / Ubuntu
sudo apt install pandoc

# Fedora
sudo dnf install pandoc

Check the result with pandoc --version. Distribution packages can lag behind the current release, and option behavior can differ across versions. If a command below does not work, compare it with the version you have and see the official installation instructions. The commands on this page were verified with Pandoc 3.9.

The basic conversion command

One input file, one output file.
bash
pandoc input.md -o output.docx

-o sets the output file, and the .docx extension tells Pandoc which writer to use. The input format is inferred from .md. Run the command from the folder that contains input.md, or use a full path.

Useful options

These are the options most often needed for Markdown-to-Word work.

Input format (gfm, markdown)

bash
pandoc input.md -f gfm -o output.docx

-f gfm selects GitHub-Flavored Markdown, which is a good match for pipe tables and task lists. Plain markdown is Pandoc's own extended dialect; the two are similar but not identical, and support has changed between versions.

Table of contents

bash
pandoc input.md -f gfm -o output.docx --toc

For DOCX, --toc inserts a table of contents field. Word may need to update the field before the entries appear with current page numbers. Depth is controlled by --toc-depth if you do not want every heading level included.

Reference document for styles

bash
# Create a starting template, then edit its styles in Word
pandoc -o custom-reference.docx --print-default-data-file reference.docx

# Use that template for the conversion
pandoc input.md -f gfm -o output.docx \
  --reference-doc=custom-reference.docx \
  --resource-path=./images

The reference file must be a real .docx. Pandoc ignores its body text and reuses its styles and page setup, so editing the styles in a copy of Pandoc's default template is the reliable way to match a house style. Without --reference-doc, Pandoc uses sensible defaults.

Images and resource paths

By default Pandoc looks for a relative image path in the working directory. If your images live elsewhere, add --resource-path=./images as in the command above. On Windows, use a semicolon to separate multiple directories. Remote images are URLs rather than local files; download them first if you need them embedded. When an image cannot be found, Pandoc warns and replaces it with a description instead of failing the whole conversion.

Batch conversion example

The same command works in a loop over every Markdown file in a folder.
bash
for file in *.md; do pandoc "$file" -f gfm -o "${file%.md}.docx"; done

This bash loop writes one.docx next to one.md, and so on. In PowerShell on Windows, the equivalent is:

powershell
Get-ChildItem *.md | ForEach-Object {
  pandoc $_.Name -f gfm -o ($_.BaseName + '.docx')
}

Quote paths that contain spaces. Both loops were run against a folder of sample Markdown files with Pandoc 3.9.

Troubleshooting

Three symptoms account for most conversion surprises.

Tables and task lists not rendering

Add -f gfm. If the result is still wrong, check pandoc --version and compare your syntax with the GFM specification; very old releases handled extensions differently.

Missing images

Look for a “Could not fetch resource” warning. Add the image folder with --resource-path, or convert from a directory where the relative paths resolve. Download remote images before converting if they must appear in the Word file.

Unexpected heading styles

Define the styles you want in a reference document and pass it with --reference-doc. Editing the generated DOCX by hand works once, but the next run will use the defaults again.

When to use a browser converter instead

If you do not need a command in a pipeline, skip the install.

Paste or open a Markdown file on the homepage to check the preview, then use the Markdown to Word converter to download an editable .docx. It runs in the browser and needs no installation. Its limits are stated openly: 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. If you prefer to build the conversion in code, the Python guide covers that approach. New to the format? Start with what an MD file is.

FAQ

Short answers about running Pandoc for this job.
Do I need Python to run Pandoc?
No. Pandoc is a standalone command-line program. Python is only needed if you call it from a script through a wrapper such as pypandoc. The commands on this page use the pandoc executable directly.
Is -f gfm always necessary?
Not always, but it is the safest choice for GitHub-Flavored Markdown. Pandoc's default markdown reader and its gfm reader enable different extensions, and behavior has changed between releases. If a table or task list is ignored, add -f gfm. The GFM specification defines the dialect.
What does --reference-doc actually do?
It supplies styles and document properties such as margins, page size, headers and footers to the generated Word file. It does not supply the document content and it does not create a template from nothing: the file must be a valid .docx, ideally produced by Pandoc and then edited in Word.
Will my LaTeX math survive the conversion?
Pandoc can convert supported inline and display math into Word equation markup. The result depends on the input syntax and on how your Word version handles those equations, so open the .docx and check complex formulas before sharing it.
Can I avoid installing anything?
Yes. The online Markdown to Word converter creates an editable .docx in your browser. You can preview the same document on the homepage before exporting.

Keep exploring