telegram-export-md

Turn Telegram's unreadable result.json export into clean, searchable Markdown files.

🌐 Languages: English · فارسی

Telegram Desktop's built-in Export chat history gives you a giant result.json (plus folders full of media) — technically complete, practically unreadable. telegram-export-md converts it into one tidy Markdown file per chat, with formatting, replies, forwards, polls, and media all preserved.

Zero dependencies. Pure Python standard library.

Before → After

Before — raw export JSON:

{"id": 183, "type": "message", "date": "2021-01-01T10:00:00",
 "from": "Arian", "text": [{"type": "plain", "text": "hello "},
 {"type": "bold", "text": "everyone"}, {"type": "plain", "text": "?"}]}

After — rendered Markdown:

**2021-01-01 10:00 — Arian**

hello **everyone**?

---

**2021-01-02 18:30 — Arian**

![](media/Gaming Crew/photo_1.jpg)

*1920×1080*

Features

• 📄 One Markdown file per chat, plus an index.md table of contents
• 🖥 Terminal UI (optional extra) — browse exports, tick chats, convert, and preview the Markdown with Textual
• 📡 fetch mode (optional extra) — pull chats straight from Telegram's servers, no desktop app needed
• 🎨 Telegram formatting preserved — bold, italic, code, pre, strikethrough, underline, links
• 💬 Replies resolved — quoted with sender and a snippet of the original message
• ↩️ Forwards, edits, and polls rendered faithfully
• 🖼 Media support — photos embed, everything else links; --copy-media makes the backup self-contained
• 🔍 Filters — pick chats by name or id, slice by date range
• 🧹 Service messages (joins, pins, calls) can be excluded
• 🐍 No dependencies — works on Python 3.10+, Windows/macOS/Linux

Install

# from PyPI
pipx install telegram-export-md

# optional: fetch mode (pull chats from Telegram's servers via their API)
pipx install 'telegram-export-md[fetch]'

# optional: terminal UI (browse + convert + preview)
pipx install 'telegram-export-md[ui]'

# or directly from this repo
uv tool install git+https://github.com/Retro-Zero/telegram-export-md.git
# or
pip install git+https://github.com/Retro-Zero/telegram-export-md.git

Usage

1. Export your data

In Telegram Desktop: Settings → Advanced → Export chat history. Tick JSON as the format and check Include photos and videos if you want media. This creates a folder containing result.json and media subfolders.

2. Convert

tg-export-md ~/Downloads/Telegram-Export -o ~/telegram-backup

Result:

telegram-backup/
├── index.md
├── Gaming Crew.md
├── Saved Messages.md
└── media/
    └── Gaming Crew/
        ├── photo_1.jpg
        └── video_1.mp4

Options

Examples

# One chat, as a searchable text archive
tg-export-md export/ -o backup --chat "Gaming Crew" --copy-media

# Everything from 2022, text only
tg-export-md export/ -o backup --since 2022-01-01 --no-media

# Point straight at the JSON file
tg-export-md export/result.json -o backup

Automatic backup with fetch

No desktop app? No problem. tg-export-md fetch pulls chats straight from Telegram's servers into the same result.json + media format the desktop export produces — so the converter above works unchanged, and you get backups you can schedule.

Setup (once)

1. Get free API keys at my.telegram.org → API development tools

2. Make the keys available — either:

   export TG_API_ID=123456
   export TG_API_HASH=yourhash
   

   or save them in ~/.config/telegram-export-md/config.ini:

   [telegram]
   api_id = 123456
   api_hash = yourhash
   

3. Install with the extra: pipx install 'telegram-export-md[fetch]'

Run

Run without flags for an interactive picker: after login it lists your chats and lets you choose which ones to export, which media types to download (photo, video, voice, audio, document, sticker, animation), and optional limits — last N messages per chat, a per-file size cap, and a date range.

tg-export-md fetch -o ~/telegram-export

The first run asks for your phone number and a login code Telegram sends you — the session is saved, so later runs are automatic. Everything the picker asks is also available as a flag, so cron jobs stay hands-free:

tg-export-md fetch -o ~/telegram-export --chat "Family" --media-types photo,video --last 500 --max-size 100mb
tg-export-md ~/telegram-export -o ~/telegram-backup

Terminal UI

Prefer pointing and clicking? tg-export-md ui launches a terminal UI (built with Textual):

1. Browse to your export folder in the file tree
2. Tick the chats you want and set options (copy media, skip service messages, output folder)
3. Hit Convert — it runs in the background with a live log
4. Preview the rendered Markdown of any chat, then go back and tweak

pipx install 'telegram-export-md[ui]'
tg-export-md ui

Notes

• Large exports — the whole result.json is loaded into memory; exports up to a few hundred MB work fine on a modern laptop. Streaming support is on the roadmap.
• Media paths without --copy-media point back into your original export folder. Use --copy-media for a backup you can move or archive.
• Restricted chats — in chats where the other side enabled Restrict saving content, the full text history still exports, but their media can't be saved by anyone (by design). fetch keeps the messages with media placeholders and prints a per-file warning, plus a "could not be saved" count in the end summary. Secret chats (end-to-end encrypted) are never visible to the API at all.
• Media availability — fetch downloads whatever media is still available at fetch time; files that are already gone are kept as references in the JSON and counted in the end summary.
• Export JSON is generated by Telegram Desktop (Windows/macOS/Linux). Exports from other clients may differ slightly — open an issue if something doesn't parse.

Roadmap

• Streaming parse for huge exports
• Support the HTML export format
• Per-year splitting (--split)
• --format obsidian for vault-friendly output

Contributing

Bug reports, feature requests, and PRs are welcome. Please open an issue first for anything beyond a small fix.

License

MIT