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
• 📡 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]'

# 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

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.
• 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