Download and archive files from Telegram channels and chats, safely and resumably.
telegram-downloader is a desktop app that bulk-downloads files (PDFs, documents, images, archives, whatever) from Telegram channels and chats you're a member of. Built for archiving large channels over time, not for quick one-off downloads.
The interesting parts are the things you don't have to think about:
- Won't get your account banned. Respects Telegram's rate limits. Sleeps the exact duration Telegram asks for when it issues a
FloodWait. Re-enqueues interrupted items instead of dropping them. Throttles and batch-pauses to stay under sustained-rate thresholds. - Resumable. - Resumable. If a run gets interrupted, the next one picks up where it left off. State is tracked in an append-only log per channel so nothing gets re-downloaded.
- Safe credentials. Session file and config are
chmod 0600from creation, atomic writes, no default-permissions window. Single-instance file lock prevents two copies from racing on state. - Safe filenames. Hostile filenames from channels can't escape the output folder. Windows reserved names, Unicode bidi spoofing, byte-length filesystem overflows, and path traversal are all handled.
- Inspectable. Every download is timed, hashed (SHA-256), and logged. "Export diagnostics" packages a redacted bundle for support.
Tested on macOS. Should work on Linux and Windows; not actively tested there.
Requires Python 3.10 or later.
git clone https://github.com/hagbard2323/telegram-downloader.git
cd telegram-downloader
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
python tg_downloader.pytelegram-downloader uses Telegram's user API (via Telethon), which means you need your own API ID and hash from Telegram, just like any other MTProto client. This is a one-time setup:
- Go to https://my.telegram.org and sign in with your phone number.
- Click API development tools.
- Fill in the "Create new application" form. App title and short name are arbitrary (e.g. "telegram-downloader", "ck"). Platform: "Desktop". URL/description can be blank.
- You'll be given an API ID (number) and API Hash (32-char hex string).
- Paste these into telegram-downloader's Login tab.
Do not share your API credentials with anyone. See SECURITY.md.
- Login tab — paste API ID, API hash, phone number. Click "Connect / Send code", enter the code Telegram sends you, click "Sign in". Session is saved; you only do this once per machine.
- Channels tab — click "Load my chats", search/sort to find what you want, select one or more channels (Ctrl/Cmd-click for multi-select).
- Download tab — pick an output folder, set file extensions to filter (e.g.
pdf,epub, or leave blank for all). Optionally set a date range. Click ▶ Start.
Speed and safety knobs:
- Concurrent downloads (1–5, default 3): how many files download at once. Higher is faster but increases flood-wait risk. 3 is safe for typical accounts.
- Delay between files (default 0.5s): throttle between queuing new downloads.
- "Stuck on scanning": it's not stuck; it's walking the message history looking for matches. Look for the heartbeat line
scanned N messages, downloaded M so far. If that keeps appearing, it's working. - FloodWait messages in the log: the tool caught a rate limit and is sleeping the requested duration. Items are automatically re-enqueued after the wait. Don't touch anything.
- "Another copy is already running": either a previous instance didn't exit cleanly, or you genuinely have one running. If neither is true, delete
~/.tg_downloader/run.lockand try again. - Something weird: click 📦 Export diagnostics on the Download tab. It produces a redacted zip (API hash truncated, phone number truncated, log tail, timing CSV tail, state summary) you can inspect or share.
- Not a bot. It operates as your user account. Bot API has different capabilities and limits.
- Not for downloading restricted content. You are responsible for respecting copyright and channel terms of service.
- Not a stealth tool. Telegram sees your requests; there's no hiding from the rate limiter, only respecting it.
- Not multi-account. One session per install. Multiple machines need separate API credentials each.
Your Telegram session file is equivalent to your Telegram password. See SECURITY.md for the full list of files telegram-downloader stores, what they contain, and what you must not do with them (spoiler: don't put the config folder in Dropbox). Threat model details are in THREAT_MODEL.md.
If you think you've leaked your session file: open the official Telegram app → Settings → Devices → terminate all sessions except the current one. Change your 2FA password if you have one.
pip install -r dev-requirements.txt
pytest -v84 tests cover the sanitizer (including property-based fuzzing via Hypothesis), the append-only state WAL, the producer/consumer downloader, cancellation semantics, FloodWait retry, path containment, and the diagnostic bundle. The suite runs in ~15 seconds and requires no network.
MIT. See LICENSE.
Functional and tested. Built as a portfolio project to explore safe concurrent I/O, credential handling, and resumable state in Python. I will respond to bug reports and security issues. Pull requests are welcome if they come with tests.
Built on Telethon. Tk used because it ships with Python and keeps the dependency count low.
Developed iteratively with AI-assisted code review (Claude, Anthropic). All architecture decisions, security properties, and test design were reviewed and understood before being accepted. The codebase went through multiple rounds of review covering concurrency correctness, credential handling, and filename sanitization.