TeleBackup SDK — High-Speed Telegram Download Engine
Multi-connection parallel file downloading for Telegram
Built on Telethon · Python 3.9+ · Windows / Linux / macOS
This is the open-source download engine that powers TeleBackup. If you need a full-featured desktop client with visual gallery, smart search, and one-click channel backup, visit chatdex.cc.
Why TeleBackup SDK?
If you've tried downloading large files from Telegram using Telethon's built-in download_media(), you've likely hit these walls:
Speed ceiling. Telethon downloads through a single MTProto connection. On a free account this tops out around 0.3–0.5 MB/s. A 2 GB video takes over an hour — if the connection doesn't drop first.
Silent throttling. Telegram's server silently imposes bandwidth limits per account. You won't see an error; your download just stalls repeatedly, tanking average throughput to unusable levels.
FloodWait punishment. Send requests too fast and Telegram locks you out with a FloodWaitError — anywhere from 30 seconds to 24 hours. Most wrappers either ignore this or leave you to handle it manually.
No resume. Connection drops at 95%? Start over. Telethon has no built-in checkpoint mechanism for partial downloads.
Cross-DC pain. Files hosted on a different datacenter than your account require special handling. Telethon doesn't handle this transparently for concurrent downloads.
TeleBackup SDK solves all of these with multi-connection parallel downloading, intelligent rate limiting, checkpoint resume, and automatic cross-DC routing.
2.16 GB file, free account, same DC — 7.55 MB/s, 2214/2214 parts, zero failures.
- Multi-connection parallel download — splits files into chunks, multiple workers download simultaneously
- Smart rate limiting — avoids FloodWait and server-side throttling penalties
- Cross-DC support — automatically detects file datacenter and routes accordingly
- Checkpoint resume — interrupted downloads pick up where they left off, not from zero
- Efficient disk I/O — no temp files, no merge step
- Account isolation — accounts are fully isolated, crash-safe
- Proxy auto-detection — tries system proxy, common local ports, falls back to direct
- Multi-account management — switch between accounts without restarting
This repository is the download engine core. If you want the complete experience — visual media gallery, smart search, one-click channel backup, and local library management — check out the full desktop client:
| Requirement | Details |
|---|---|
| Python | >= 3.9 |
| OS | Windows 10+, Linux, macOS |
| Network | Telegram API accessible (direct or via proxy) |
You need a Telegram API ID and API Hash from my.telegram.org, and at least one Telethon .session file.
| Package | Purpose | Install |
|---|---|---|
| Telethon >= 1.38.0 | Telegram MTProto client | Required |
| psutil >= 5.9.0 | Process monitoring | Required |
| cryptg >= 0.4.0 | Encryption acceleration (~10x faster) | Recommended |
| PySocks >= 1.7.0 | SOCKS proxy support | Optional |
# From PyPI
pip install teleget9527
# Recommended: with encryption acceleration
pip install teleget9527[fast]
# Full install (encryption + proxy)
pip install teleget9527[all]
# From source
git clone https://github.com/xwc9527/TeleGet.git
cd TeleGet
pip install -e ".[all]"cp .env.example .envEdit .env with your API credentials and session path. See .env.example for all available options.
Place your Telethon .session file in the session directory:
data/
└── your_account_id/
└── session.session
python test_login.pypython test_real_download.pyimport asyncio
from tg_downloader import TGDownloader
async def main():
downloader = TGDownloader(
api_id=12345678,
api_hash="your_api_hash",
session_dir="./data",
)
await downloader.start("my_account")
request_id = await downloader.download(
chat_id=-1001234567890,
msg_id=42,
save_path="./downloads/video.mp4",
progress_callback=lambda dl, total, pct: print(f"{pct:.1f}%"),
)
# Wait for completion...
await downloader.shutdown()
asyncio.run(main())The SDK provides 4 async methods: start(), download(), cancel(), shutdown().
What TeleBackup SDK Handles
If you're building a Telegram downloader and hitting these errors, TeleBackup SDK already handles them:
FloodWaitError: A wait of X seconds is required— Telegram locks you out for sending requests too fast. Auto-detects and decelerates before this happens.FloodPremiumWaitError— Free accounts get throttled 7–11 seconds per hit. Handles the backoff transparently.FILE_REFERENCE_EXPIRED/FILE_REFERENCE_INVALID— File metadata goes stale after ~1 hour. Auto-refreshes without restarting the download.AUTH_KEY_UNREGISTERED— DC auth key invalidated server-side. Rebuilds authorization automatically.AuthBytesInvalidError— Cross-DC auth race condition that crashes most implementations. Prevented entirely.Server closed the connection/ConnectionError— Telegram drops sockets under load. Recovers without losing progress.0 bytes read on a total of 8 expected bytes— Silent connection death. Detects and reconnects.asyncio.TimeoutError— Requests hang indefinitely. Enforces per-request timeouts and rotates to healthy connections.WinError 32: The process cannot access the file— Windows file locking during rename. Retries automatically.
- Single-connection speed ceiling (0.3–0.5 MB/s) → Multi-connection parallel download, 7+ MB/s on free accounts
- Undocumented rate limits → Multi-layer adaptive rate limiting that auto-tunes to your account's limits
- FloodWait cascading failures → Circuit breaker hierarchy isolates failures per-connection
- Cross-DC file download → Automatic DC detection, dedicated connection pool per datacenter
- Cross-DC
AuthBytesInvalidError→ Race condition prevention for concurrent auth exports - No download resume → Part-level checkpoint persistence, survives crashes and restarts
- Cross-session resume → Switch accounts or restart app, download continues from where it left off
- Connection storms after "Server closed" → Disconnect detection with coordinated recovery
- Download stalls at 99% → Watchdog detects stuck workers and force-restarts them
- Disk I/O bottleneck → Sparse file pre-allocation, direct offset writes, no temp files or merge step
- Multi-account auth collision → Process-level account isolation, zero shared state
FloodWaitError — Handled automatically. If frequent, increase rate_limiter_interval.
FloodPremiumWaitError — Free account throttling. Lower connection_pool_size to reduce frequency.
FILE_REFERENCE_EXPIRED — Auto-refreshed up to 3 times. If persistent, the message may have been edited or deleted.
AUTH_KEY_UNREGISTERED — Auto-recovered. If persistent, your .session file may be corrupted — re-login.
Download stalls — Watchdog auto-recovers after 30s. Check logs for [WATCHDOG] entries.
WinError 32 — Auto-retried. If persistent, another process may be holding the file open.
How to maximize Telegram download speed on a free account?
TeleBackup SDK uses multi-connection parallel downloading to fully utilize the bandwidth Telegram allocates per account. By opening multiple MTProto connections and downloading different file parts simultaneously, it reaches 7+ MB/s on free accounts — compared to 0.3–0.5 MB/s with single-connection approaches like Telethon's built-in download_media().
What happens when a download is interrupted?
TeleBackup SDK persists download progress at the part level. If the process crashes, the network drops, or you restart the application, the download resumes from the last completed part — not from the beginning. This works across sessions and even across account switches.
How does it handle Telegram's rate limits and FloodWait?
TeleBackup SDK implements multi-layer adaptive rate limiting with per-connection circuit breakers. It monitors server responses in real time and automatically decelerates before hitting FloodWaitError thresholds, keeping your account safe while maintaining maximum throughput.
Can it download files from a different Telegram datacenter?
Yes. TeleBackup SDK automatically detects which datacenter hosts the target file and manages dedicated connection pools per DC. It handles cross-DC authorization seamlessly, including the AuthBytesInvalidError race condition that breaks most other implementations.
What is the difference between TeleBackup SDK and TeleBackup Desktop?
This SDK is the open-source download engine — it provides the core parallel downloading capability as a Python library. TeleBackup Desktop is the full-featured desktop application built on top of this engine, adding a visual media gallery, smart search, channel browsing, and one-click backup with a graphical interface.
AGPL-3.0 — see LICENSE for details.