telegram-turbo-downloader

Fast, multi-connection Telegram file downloader with a terminal UI (TUI).
Open a channel or bot, fuzzy-find the files you want, and download them in parallel — right from your terminal.

telegram-turbo-downloader is a fast Telegram download manager for the terminal. It downloads large files (movies, series, archives, backups) from Telegram channels, groups, and search bots using multiple parallel connections, so a 2 GB video that normally crawls at 0.3–0.5 MB/s finishes in minutes instead of hours. It ships as a clean TUI (text user interface) — no browser, no bloated desktop client, no manual message-ID hunting.

Why is downloading from Telegram so slow? The standard Telegram client and most libraries pull a file through a single MTProto connection, which is heavily rate-limited on free accounts. This tool opens a pool of connections and fetches many chunks of the file at once, then reassembles them — dramatically increasing throughput. It also handles cross-datacenter (cross-DC) routing and resumes interrupted downloads automatically.

Table of contents

• Features
• Installation
• Quick start
• Usage
• How it works
• Configuration
• FAQ
• Credits
• License

Features

• ⚡ Parallel multi-connection downloads — saturate your bandwidth instead of one slow MTProto stream.
• 🔎 Fuzzy-find & browse — open any channel or bot to list its recent files, then fuzzy-find (fzf-style, entirely local, instant) to narrow the list as you type.
• ✅ Multi-select download queue — tick several episodes/files and download the whole batch unattended.
• 📊 Live TUI dashboard — real-time per-file progress bars, speed, ETA, and part counts.
• ⏸️ Automatic resume — interrupted transfers continue from where they stopped (sparse .part scanning), no re-downloading finished chunks.
• 🌍 Cross-DC aware — correctly downloads files hosted on a different Telegram datacenter than your account.
• 📁 Smart output folders — auto-sorts files into Show/S01/… or Movie (Year)/… from the filename.
• 🖥️ Cross-platform — Windows, macOS, and Linux; pure terminal, works over SSH.

Installation

Requires Python 3.9+.

From PyPI (recommended)

pip install telegram-turbo-downloader

# optional extras: faster decryption + SOCKS/HTTP proxy support
pip install "telegram-turbo-downloader[all]"

From source

git clone https://github.com/s21v1d9p/telegram-turbo-downloader.git
cd telegram-turbo-downloader
pip install -e ".[all]"

Quick start

1. Get Telegram API credentials at https://my.telegram.org → API development tools. You'll get an API_ID and API_HASH.

2. Configure — copy the example env file and fill it in:

   cp .env.example .env
   # edit .env: set API_ID and API_HASH
   

3. Log in once (creates a reusable session):

   telegram-turbo-downloader-login
   

4. Launch the app:

   telegram-turbo-downloader
   

   (Both commands also have a short alias: ttd-login / ttd.)

Usage

Inside the TUI:

1. Open a channel/bot — type a username like @some_channel or @SomeSearchBot (or a numeric -100… id) and press Open to list its recent files.
2. Fuzzy-find — press / (or f) to jump to the find box and type; the visible list narrows instantly as you type (fzf-style, entirely local — matches filename or message ID, no need to press anything else).
3. Select — press Space to tick a file, A to select all, N to clear.
4. Download — press D. The dashboard shows every file downloading in parallel with live speed and ETA.

Downloaded files are saved under ~/Downloads/ by default, auto-organized by show and season.

How it works

telegram_turbo_downloader/
  app.py           terminal UI entry point (`telegram-turbo-downloader`)
  login.py         one-time session login (`telegram-turbo-downloader-login`)
  tui/             Textual screens: search/browse + live download dashboard
  core/            orchestration: connect, search bot, per-file download logic
  engine/          high-speed parallel download engine (bundled dependency)

The core/ layer resolves a message's file, splits it into 1 MB parts, preallocates a sparse file, and hands the parts to a worker pool that fetches them concurrently across a pool of Telegram connections. Progress is streamed back to the TUI. Finished transfers are atomically renamed from *.part to the final file.

Configuration

.env keys:

Environment overrides:

TTD_JOBS=6 telegram-turbo-downloader

FAQ

How do I download large files from Telegram quickly? Use a multi-connection downloader like this one. Single-connection downloads are rate-limited; parallel chunked downloading is far faster.

Can it download from Telegram search bots? Yes — open the bot's chat like any other source to list the files it has already posted there, then fuzzy-find to narrow the list. The app doesn't message the bot with a query on your behalf; if the bot needs you to message it first to get results, do that in the Telegram app, then open the same chat here.

Does it resume interrupted downloads? Yes — automatically. Re-run the download and it skips already-completed chunks.

Is a premium Telegram account required? No. It works on free accounts; premium accounts simply get higher throughput.

Where are files saved? Under ~/Downloads/, auto-sorted into show/season or movie folders based on the filename.

Credits

The bundled parallel download engine in telegram_turbo_downloader/engine/ is derived from the open-source TeleBackup SDK by xwc9527/telebackup (also on PyPI as teleget9527), redistributed under the AGPL-3.0 license. The only change from upstream is that in-code comments and log/UI strings were translated from Chinese to English; the program logic is unchanged. All credit for the download engine goes to its original authors. See NOTICE for details.

The terminal UI, search/browse/queue orchestration, and documentation are original work.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE. Because the bundled engine is AGPL-3.0, this project (as a whole) is distributed under the same license.