How to see .md files formatted in Quick Look on a Mac

Why does Quick Look show a .md file as # and ** symbols?

Quick Look shows a .md file as # and ** symbols because it shows each file the way macOS knows how, and macOS doesn't know Markdown.

Apple describes Quick Look as "a fast, full-size preview of nearly any kind of file without opening the file" (Apple Support). For a .md file, "nearly any" means the raw text. You see the symbols, not the page they describe.

Apps can teach Quick Look new tricks. A developer adds a Quick Look extension, a small add-on that tells Quick Look how to draw a file type (Apple developer docs). Install one for Markdown and the spacebar shows headings, lists and tables.

Which Quick Look extension should I use for .md files?

For most people, QLMarkdown is the Quick Look extension to use for .md files on a Mac. It's free, open source, still updated, and it draws tables, diagrams and math. This table compares five ways to get a formatted Markdown preview in Quick Look.

Prices and requirements checked 28 September 2026. "Not listed" means the developer's page doesn't mention it, not that we tested it and it failed.

A few honest notes:

• QLMarkdown has had regular releases through September 2026 (version 1.5.4 on 18 September), and its developer says the app is signed and notarized by Apple since version 1.5.0 (release notes). It isn't meant as a reader on its own. Its app is where you change settings.
• Imark is a young app (version 0.6.2), so expect some rough edges.
• PreviewMarkdown shows a placeholder instead of images, because macOS only lets it read the file you're previewing (developer's page).
• Marked Quick Look lists the most extras, such as a table of contents for long files and a tidy view of the details block some files start with (called frontmatter). It also costs the most.

Some full Markdown apps include a Quick Look extension too. Peekdown ($4.99, macOS 15 or later) and MacMD Viewer ($19.99, macOS 14 or later) both do (checked 28 September 2026).

How do I turn on a Markdown Quick Look extension?

To turn on a Markdown Quick Look extension on a Mac, install its app, open it once, then switch the extension on in System Settings. That last step is in a different place depending on your macOS version.

1. Install the app. Drag it into your Applications folder, or install it from the App Store.
2. Open the app once. This is how your Mac finds the extension inside it. QLMarkdown's instructions say you "must launch the application at least once" (QLMarkdown README). You can close it straight after.
3. Turn the extension on.
   • macOS 15 or later (including macOS 26 and 27, checked 28 September 2026): choose Apple menu › System Settings, click General, then Login Items & Extensions. Find Quick Look under Extensions, click the ⓘ button next to it, turn on the extension, and click Done (Apple Support).
   • macOS 13 or 14: choose Apple menu › System Settings, click Privacy & Security, then Extensions on the right, then Quick Look (Apple Support).
4. Test it. Select a .md file in Finder and press Space. You should see a formatted page.

Not sure which macOS you have? Choose Apple menu › About This Mac.

open it once. that's the step everyone skips.

What if Quick Look still shows a .md file as plain text?

If Quick Look still shows a .md file as plain text after you install an extension, work down this list. Most fixes take seconds.

• You haven't opened the app yet. Open it once, quit it, then try Space again.
• The extension is switched off. Check the Quick Look list in System Settings, using the steps above.
• Two Markdown extensions are on. Turn off the ones you're not using, so you know which one you're seeing.
• Another app has claimed .md files. PreviewMarkdown's developer notes that if another app owns the Markdown file type on your Mac, their extension can't preview it (developer's page). If .md files open in Xcode or something unexpected, change the default app for .md files first.
• You followed an old guide. Older add-ons ended in .qlgenerator and were copied into a QuickLook folder. Those stopped working in macOS 15, which only uses the newer kind that lives inside an app (The Eclectic Light Company). Use one of the options in the table above instead.
• Still nothing. Restart your Mac. If you're comfortable in Terminal, qlmanage -r resets Quick Look. It's harmless, though thumbnails may be slow for a little while afterwards (The Eclectic Light Company).

What can't a Quick Look preview of a .md file do?

A Quick Look preview of a .md file can't be edited, searched or navigated by heading. Quick Look is built for a quick peek, and that's by design.

• It's temporary. Press Space again, or click the close button, and it's gone (Apple Support).
• You can't edit. To fix a line you still need to open the file in an app.
• You can't search it. There's no Find bar for jumping to the one word you need in a long file.
• There's no outline. You scroll a long plan top to bottom with no list of sections.
• Each extension draws things differently. A diagram or wide table can look fine in one and cramped in another.

For "is this the right file?", a preview is all you need. For a 3,000-word plan you need to understand before you approve it, it gets tiring fast.

When is a Markdown reader better than Quick Look?

A Markdown reader is better than Quick Look when you actually need to read the .md file, not just check it. A reader app stays open, remembers where you were, and gives you tools the preview doesn't.

Here's what that looks like in One Clear Reader, which opens .md files when you double-click (or paste a path, or type part of the name):

• Find with ⌘F, with every match highlighted.
• An outline of the headings in a sidebar, so you can jump to a section.
• Wide tables that scroll sideways with "More columns" buttons, and diagrams drawn from Mermaid code.
• Reading settings, like the Neuro-friendly profile with the Atkinson Hyperlegible font and extra spacing, or larger text.
• Editing the Markdown when you spot a mistake, free, with a check of the changes before anything is saved.

Plenty of people use both. Quick Look for a glance in Finder, a reader for anything longer than a screen. If you're choosing a reader, Markdown readers for Mac, compared lays out the options side by side.

What's the free way to fix the spacebar preview for .md files?

The free way to fix the spacebar preview for .md files is QLMarkdown: install it, open it once, switch it on, and press Space. That costs nothing and fixes the preview in Finder.

When you want a proper page for longer documents, One Clear Reader is free for reading, search and editing Markdown, with no account and no time limit on the free version. Set it as your default with one click, and double-click does the rest. How to open a .md file on a Mac walks through the first open.

Questions people ask