How to Open .md Files on Mac
5 easy ways to view Markdown files on macOS
You’ve downloaded a project from GitHub, cloned a repo, or received a file ending in .md — and macOS doesn’t know how to open it properly. Not sure what that file is? Read what an .md file is first. If you need to open md file on a Mac, here are five ways to do it, from the quickest to the most powerful. Looking for cross-platform options? See our MD file viewer guide.
1. Use a Dedicated Markdown Viewer (Recommended)
The fastest way to read .md files on macOS is with a dedicated md reader like MDViewer.
- Download and install MDViewer
- Right-click any
.mdfile in Finder - Choose Get Info
- Under "Open with", select MDViewer
- Click Change All to set it as your default for all .md files
After this, every .md file opens with a double-click — rendered with headings, code blocks, tables, and links, just like on GitHub. MDViewer also gives you a table of contents, tabs for multiple files, and built-in Git history.
2. Open from Terminal
If you work in the terminal, you can open .md files directly:
open README.md— opens in your default .md appopen -a MDViewer README.md— opens in MDViewer specificallyopen -a "TextEdit" README.md— opens in TextEdit (raw text, no rendering)
Once you set MDViewer as your default, open README.md is all you need.
3. Quick Look Preview in Finder
Select any .md file in Finder and press Space to see a formatted preview instantly — no app launch needed. By default, macOS shows raw Markdown source, but MDViewer includes a built-in QuickLook extension that renders headings, code blocks, tables, and even Mermaid diagrams right in the preview panel.
This is the fastest way to open md file contents without leaving Finder. Works in column view, Cover Flow, and full-screen Quick Look. The extension installs automatically with MDViewer — no plugins or extra setup.
4. Open in TextEdit
macOS includes TextEdit, which can open .md files:
- Right-click the .md file in Finder
- Choose Open With → TextEdit
TextEdit shows the raw Markdown syntax — you'll see # Heading instead of a formatted heading, and **bold** instead of bold text. If you're new to the syntax, our Markdown cheat sheet covers all the formatting basics. Fine for quick edits, but not for reading.
5. Open in VS Code or Xcode
Both VS Code and Xcode can render Markdown files:
- VS Code: Open the file, then press ⌘⇧V to open the Markdown preview pane
- Xcode: Simply open the file — Xcode renders basic Markdown automatically
These work, but they’re heavy applications designed for coding — not for reading documentation. Launching a 300 MB+ app to read a README is slower than using a lightweight, dedicated viewer. See our Markdown editor vs. viewer guide for a deeper comparison.
Comparison: 5 Ways to Open Markdown on Mac
Here’s how each method compares for reading and previewing .md files on macOS:
| Method | Renders Formatting | Launch Speed | GFM Support | Best For |
|---|---|---|---|---|
| MDViewer | Full | Instant | Tables, Mermaid, task lists | Daily Markdown reading |
| Quick Look | With extension | Instant | Via MDViewer extension | Quick peek in Finder |
Terminal (open) | Depends on default app | Instant | Depends on app | CLI workflows |
| TextEdit | No (raw text) | Fast | None | Quick edits |
| VS Code | Yes (preview pane) | Slow (~3 s) | Tables, task lists | Editing code + docs |
For a deeper look at viewer options, see our best Markdown viewers for Mac comparison.
Why Use a Dedicated .md Reader?
- Speed — MDViewer launches instantly; VS Code and Xcode take seconds
- Rendering — full GitHub Flavored Markdown: tables, task lists, code highlighting
- Navigation — table of contents for long documents, tabs for multiple files
- Git integration — browse file history and diffs without the terminal
- Finder integration — set as default and double-click to open, just like Preview handles PDFs
Not sure what .md files are in the first place? Read our guide on what an .md file is — it covers the format, where you’ll encounter it, and why it matters.
Troubleshooting: .md File Opens as Plain Text
If you double-click an .md file and see raw syntax (# Heading, **bold**) instead of formatted text, your Mac is opening it in a plain-text editor. Here’s how to fix it:
- Right-click the
.mdfile in Finder - Choose Get Info (or press ⌘I)
- Under “Open with”, click the dropdown and select MDViewer
- Click Change All… → Continue
After this, every .md file on your Mac opens with rendered formatting: headings, tables, code blocks, and Mermaid diagrams. The change applies system-wide — Finder, Terminal (open command), and Spotlight all use the new default.
If you don’t want to install an app, use the free online Markdown viewer — drag and drop any .md file to see it rendered instantly in your browser.
Opening README.md from GitHub Locally
When you clone a GitHub repo, the README.md file is just a regular Markdown file on your disk. GitHub renders it automatically on the web, but your Mac doesn’t:
- From Finder: navigate to the cloned repo folder, find
README.md, and double-click it. With MDViewer set as default, it opens with full GitHub-style formatting. - From Terminal:
open README.mdin the repo directory. This is the fastest way if you’re already working in the terminal. - Quick Look: select
README.mdin Finder and press Space — MDViewer’s QuickLook extension renders the formatted preview without opening the app.
MDViewer renders the same tables, task lists, and Mermaid diagrams that GitHub shows — so your local README looks identical to the one on github.com.
Frequently Asked Questions
How do I open an .md file on Mac without installing anything?
Select the .md file in Finder and press Space to use Quick Look. macOS shows raw Markdown by default, but it lets you read the content immediately. For rendered formatting, open the file in TextEdit or use the free online Markdown viewer right in your browser.
What is the default app for .md files on macOS?
macOS has no built-in default for .md files — Finder may open them in Xcode or TextEdit depending on what's installed. To set a default: right-click any .md file, choose Get Info, change "Open with" to your preferred app (e.g. MDViewer), and click Change All.
Can I preview Markdown files directly in Finder?
Yes. Select any .md file and press Space for Quick Look. By default macOS shows raw text, but MDViewer includes a free QuickLook extension that renders headings, code blocks, tables, and Mermaid diagrams right in the preview panel — no app launch needed. See our Markdown preview on Mac guide for more details.
How do I open .md files on Windows or iPhone?
On any platform, use the free online Markdown viewer — drag and drop your .md file to see it rendered with full formatting. On Windows, VS Code or Notepad++ can also open Markdown files. On iPhone, you can view .md files in the Files app or use the online viewer in Safari.
How do I preview Markdown files on Mac?
The quickest way is Quick Look — select the .md file in Finder and press Space. With MDViewer installed, Quick Look renders full Markdown formatting including headings, tables, and code blocks. For a full preview experience, open the file in MDViewer, which provides live rendering, table of contents, and tabs. See our detailed Markdown preview on Mac guide.
What is the best Markdown reader for Mac?
MDViewer is a free, lightweight Markdown reader built specifically for macOS. It launches instantly, renders GitHub Flavored Markdown with Mermaid diagrams, provides a table of contents for navigation, and integrates with Finder as a default app for .md files. See our best Markdown viewers for Mac comparison for alternatives.
Why does my .md file open as plain text on Mac?
macOS has no built-in Markdown renderer — it treats .md files as plain text and opens them in TextEdit or Xcode, showing raw syntax instead of formatted content. To fix this, set a dedicated viewer like MDViewer as the default app: right-click any .md file → Get Info → change “Open with” → Change All. After that, every .md file opens with formatted headings, tables, and code blocks.
How do I open a README.md file from GitHub on my Mac?
After cloning a repo, the README.md is a regular file on your disk. Double-click it in Finder (with MDViewer set as default) or run open README.md in Terminal. MDViewer renders the same GitHub Flavored Markdown — tables, task lists, and Mermaid diagrams — so it looks identical to what you see on github.com.
Get MDViewer
Free, native, and built specifically for reading Markdown on macOS. Need a quick look without installing anything? Use the online Markdown viewer right in your browser. Learn more in our guide to viewing Markdown online.
Requires macOS 13.0 or later. Intel and Apple Silicon.