A unified streaming and downloading interface for Telegram. TGrab allows you to browse, preview, and batch download media from any channel or group with zero friction.
- 🚀 Instant Cataloging: Lists all your joined channels and groups immediately.
- 🖼️ Real-time Streaming: Media items stream into the UI as they are discovered—no waiting for full scans.
- ⚡ Virtual Layout: Handles 100,000+ items smoothly using a custom JS-based virtualized grid.
- 🎬 Smart Previews: Hover to play videos, instant lightbox for photos, and lazy-loaded thumbnails.
- 📂 Automatic Organization: Downloads are saved to
~/Downloads/telegram/<channel_name>/. - 🔄 Resume Support: Skips already downloaded files and resumes interrupted jobs.
- 📦 Zero Config: Auth once via OTP, and the session is cached securely in
tg.session.
The fastest way to run TGrab without managing environments.
uv run app.pypython3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.pyOnce running, open http://localhost:7861 in your browser.
- Get your API ID and API Hash from my.telegram.org.
- Launch TGrab and enter your credentials.
- Enter your phone number (with country code, e.g.,
+1234567890). - Enter the OTP sent by Telegram.
- You're in! Credentials and session are stored locally and won't be requested again.
| File | Description |
|---|---|
app.py |
FastAPI backend & API routing. |
core.py |
Telethon logic & media streaming engine. |
db.py |
SQLite persistence for metadata & history. |
config.py |
App-wide constants and path settings. |
static/ |
Vanilla JS/CSS frontend (Zero dependencies). |
- Local-first: All session data, API keys, and media metadata stay on your machine.
- No Cloud: TGrab does not send your data to any any server besides Telegram's official MTProto endpoints.
- Open Source: Audit the code yourself—it's less than 2k lines of Python.
Distributed under the MIT License. See LICENSE for more information.