⚡ MarkItDown Local Frontend

v0.44.3 - Convert documents, PDFs, Office files & more to Markdown, locally. Available for macOS (v0.44.3 release) and Windows (v0.44.3 release), both shipping app v0.44.3.

A self-contained web app built on Microsoft's MarkItDown library. All conversion happens on your machine. No files or URLs are ever sent to an external server.

---

Features

• Drag-and-drop or browse to upload files
• URL conversion — paste a YouTube link or any web page URL
• Live Markdown preview alongside the raw output
• Copy to clipboard or download as .md
• Stats bar — characters, words, lines, and estimated token range
• Quit button — shuts down the server and shows a clean stopped page
• Auto-quit on tab close — closing the browser tab automatically exits the app

Supported formats

Category	Formats
Documents	PDF, DOCX, PPTX, XLSX, XLS, EPUB
Data	CSV, JSON, XML
Web	HTML, YouTube URLs, web pages
Archives	ZIP
Images	JPG, PNG
Audio	WAV, MP3

Max file size: 100 MB

---

Option 1 — Run as a macOS App (recommended)

Download the MarkItDown.dmg installer from the v0.44.3 Release page. No Python installation required.

Steps

1. Download MarkItDown.dmg from the v0.44.3 release.
2. Double-click the DMG to open it.
3. Drag MarkItDown.app (left) into the Applications folder (right).
4. Eject the DMG.
5. Open Applications in Finder and right-click MarkItDown.app → Open → click Open in the dialog.

   This one-time step is required because the app is not signed with an Apple Developer ID. After the first launch you can double-click as normal.

6. Your default browser opens automatically to http://127.0.0.1:5001.
7. To quit, click the Quit button in the top-right corner of the UI, or simply close the browser tab — the app exits automatically.

Requirements

• macOS 12 (Monterey) or later
• Apple Silicon (arm64) or Intel Mac

---

Option 2 — Run as a Windows App

Download MarkItDown.exe from the v0.44.3 release page. No Python installation required.

Version note: the version shown in the app UI comes from app.py (the single source of truth for the app version). The v0.44.3 release carries both the macOS .dmg and the Windows .exe, and both ship app v0.44.3.

On Windows the app binds only to 127.0.0.1, so no Defender Firewall prompt appears and nothing is exposed to your network. If the app cannot start, it shows an error dialog and writes details to %LOCALAPPDATA%\MarkItDown\markitdown.log. Every released EXE has passed an automated launch-and-convert test on a clean Windows machine in CI.

Steps

1. Download MarkItDown.exe from the v0.44.3 release.
2. Double-click MarkItDown.exe to launch it.

   Windows SmartScreen warning: Click More info → Run anyway. This one-time step is required because the app is not code-signed. After the first launch you can double-click as normal.

3. Your default browser opens automatically to http://127.0.0.1:5001.
4. To quit, click the Quit button in the top-right corner of the UI, or simply close the browser tab — the app exits automatically.

Requirements

• Windows 10 or Windows 11 (64-bit)

---

Option 3 — Run from Source (Python)

Use this if you want to modify the app or the pre-built .app doesn't work on your system.

Requirements

• macOS 12 or later (also works on Windows)
• Python 3.10 or higher (developed on 3.14; official Windows builds use 3.12)

Check your Python version in Terminal:

python3 --version

If you have 3.9 or lower, download the latest Python from python.org.

One-time setup (macOS)

Open Terminal (Cmd + Space → type Terminal → press Enter) and run each command:

# 1. Navigate to the project folder
cd /path/to/CC_Markdown

# 2. Create a virtual environment
python3 -m venv .venv

# 3. Activate it (your prompt will show (.venv) when active)
source .venv/bin/activate

# 4. Install dependencies (pinned versions)
pip install -r requirements.txt

Tip: If you see an Xcode prompt, click Install and wait for it to finish, then re-run the pip install command.

Running the app

cd /path/to/CC_Markdown
source .venv/bin/activate
python app.py

The app starts a local server and opens http://127.0.0.1:5001 in your browser automatically.

To stop, click the Quit button in the UI, close the browser tab, or press Control + C in Terminal.

One-time setup (Windows)

Open Command Prompt (Win + R → type cmd → Enter):

cd C:\path\to\CC_Markdown
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Note: If Python is not found, re-run the installer from python.org and check "Add Python to PATH".

Run:

python app.py

---

Option 4 — Build the Windows EXE Yourself

Use this to rebuild MarkItDown.exe after making changes to app.py. The GitHub Actions workflow smoke-tests every build: it launches the EXE on the runner, converts a sample file over HTTP, and verifies clean shutdown before the artifact is uploaded or released.

Requirements

• A GitHub account with a fork of this repository (the build runs in GitHub Actions on a Windows runner — no local Windows machine needed)
• Alternatively: a Windows machine with Python 3.10+ (pip install -r requirements.txt includes PyInstaller)

Build via GitHub Actions

1. Push your changes to your repository.
2. Go to Actions → Build Windows EXE → Run workflow.
3. Download MarkItDown-Windows-x64.zip from the completed run's artifacts.
4. Extract the zip — MarkItDown.exe is inside.

Build locally on Windows

Open Command Prompt and run:

cd C:\path\to\CC_Markdown
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pyinstaller MarkItDown_win.spec --noconfirm

Output: dist\MarkItDown.exe (single self-contained executable, ~120 MB)

---

Option 5 — Build the macOS App Yourself

Use this to rebuild MarkItDown.app after making changes to app.py.

Additional requirement

None beyond the one-time setup: requirements.txt already includes PyInstaller and Pillow (pip install -r requirements.txt).

Build

bash build.sh

The script will:

1. Kill any running instance on port 5001
2. Clean previous build artifacts
3. Run PyInstaller with MarkItDown.spec
4. Ad-hoc sign the .app bundle
5. Create a MarkItDown.dmg installer with a drag-to-Applications layout
6. Report the bundle and DMG size and location

Output: dist/MarkItDown.app (~166 MB) and dist/MarkItDown.dmg (~90 MB)

First launch on another Mac: Right-click → Open → Open (one-time Gatekeeper bypass). This is expected for apps without an Apple Developer ID.

---

Troubleshooting

Problem	Fix
Port 5001 already in use	Nothing to do: if another MarkItDown is running, the app opens a tab to it; if another program owns the port, the app falls back to 5002-5010 automatically. As a last resort: macOS lsof -ti :5001 | xargs kill -9, Windows netstat -ano | findstr :5001 then taskkill /PID <pid> /F
"MarkItDown failed to start" dialog (Windows)	Open %LOCALAPPDATA%\MarkItDown\markitdown.log for the full error (macOS equivalent: ~/Library/Logs/MarkItDown/markitdown.log)
Windows SmartScreen blocks the EXE	Click More info → Run anyway (one-time, no certificate)
Audio (MP3/WAV) transcription fails	Install ffmpeg and make sure it is on PATH; transcription also needs internet access (Google speech API)
Image metadata missing from output	Optional: install exiftool for richer image/audio metadata
App didn't quit after closing tab	The watchdog allows 12 s after the last heartbeat — wait a moment
App won't open on another Mac	Right-click → Open → Open (one-time Gatekeeper step)
"command not found: pip"	Use python3 -m pip install ... instead
Xcode prompt on macOS	Click Install, wait for it to finish, re-run pip install
URL conversion says the address is not allowed	The URL box accepts public http/https addresses only; local paths and private-network or loopback addresses are rejected on purpose
Conversion returns empty output	Check the error box in the UI for the full Python traceback

---

Project structure

CC_Markdown/
├── app.py                  # Single-file Flask app (HTML/CSS/JS embedded)
├── requirements.txt        # Pinned dependencies (runtime + build tools)
├── MarkItDown.spec         # PyInstaller config — macOS .app bundle
├── MarkItDown_win.spec     # PyInstaller config — Windows .exe (onefile)
├── windows_version_info.txt # Windows EXE version resource (sync with app.py)
├── make_icon.py            # Generates the app icon (PNG + Windows .ico)
├── MarkItDown_icon.ico     # Windows EXE icon (committed, from make_icon.py)
├── build.sh                # macOS build script (clean → bundle → sign → DMG)
├── .github/
│   └── workflows/
│       └── build-windows.yml  # GitHub Actions workflow — builds Windows EXE
├── dist/
│   └── MarkItDown.app      # Pre-built macOS application
└── .venv/                  # Python virtual environment (not committed)

---

Limitations

• Both binaries are unsigned (no Apple Developer ID, no Windows code-signing certificate), so macOS Gatekeeper and Windows SmartScreen each show a one-time warning. The Windows EXE ships an icon and version metadata, which improves the SmartScreen dialog, but only code signing removes it.
• Audio transcription (MP3/WAV) requires ffmpeg on PATH and internet access; it is the only feature that sends data off the machine (audio goes to the Google speech API).
• exiftool is optional; without it, image and audio conversions omit detailed metadata.

---

License

MIT — see LICENSE.

Built on Microsoft MarkItDown (MIT).