telegram-turbo-downloader 0.1.1

Fast, multi-connection Telegram file downloader with a terminal UI (TUI).

telegram-turbo-downloader

Fast, multi-connection Telegram file downloader with a terminal UI (TUI).
Search a channel or bot, tick 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.
• 🔎 Search bots & browse channels — type a query, the app sends it to the bot and harvests the files it returns; or list a channel's recent files.
• ✅ 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 recent files.
2. Search — type a query (e.g. Panchayat S01) and press Search. The app messages the bot and collects the files it posts back.
3. Filter — narrow the visible list as you type.
4. Select — press Space to tick a file, A to select all, N to clear.
5. Download — press D. The dashboard shows every file downloading in parallel with live speed and ETA.

Key	Action
Space	Select / deselect the highlighted file
A / N	Select all / clear selection
D	Download selected files
R	Refresh the current listing
B	Back to browse (from the dashboard)
Q	Quit

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:

Key	Description
API_ID, API_HASH	Your Telegram API credentials (required)
SESSION_DIR	Where session files are stored (default ./data)
DOWNLOAD_ACCOUNT	Account label used for the session folder
DOWNLOAD_CHANNEL	Optional channel/bot to open on launch

Environment overrides:

Variable	Description
TTD_JOBS	Number of parallel connections/workers (default 5). For free accounts, 5–6 is a good ceiling for cross-DC downloads.

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. Enter the bot's username, type your query, and the app harvests the files the bot replies with.

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.