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
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
macOS / Windows / Linux package managers
# 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 pandocCheck 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
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
Input format (gfm, markdown)
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
pandoc input.md -f gfm -o output.docx --tocFor 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
# 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=./imagesThe 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
for file in *.md; do pandoc "$file" -f gfm -o "${file%.md}.docx"; doneThis bash loop writes one.docx next to one.md, and so on. In PowerShell on Windows, the equivalent is:
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
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
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
Do I need Python to run Pandoc?
Is -f gfm always necessary?
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?
Will my LaTeX math survive the conversion?
Can I avoid installing anything?
Keep exploring
Related tools and guides
- Markdown to Word (DOCX)Export Markdown as an editable Word document, including supported equations.
- Markdown to Word in PythonA working Python example, its limits, and a no-code alternative.
- Markdown Viewer & Live PreviewPaste Markdown or open a local file and preview the formatted result as you type.
- What Is an MD File?What Markdown files contain and how to open, view and convert them.