telegram_media_downloader: Download Telegram Media with Ease

telegram_media_downloader: Download Telegram Media with Ease

Summary

telegram_media_downloader is a powerful, cross-platform tool designed to download media files from Telegram conversations, chats, and channels. It supports various media types and offers flexible download options, including a web UI and bot commands. Users can easily manage downloads, configure filters, and even upload files to cloud drives.

Repository Info

Updated on November 14, 2025
View on GitHub

Tags

telegram-botmedia-downloadercross-platformpythonflasktelegram-toolsdownloader

Click on any tag to explore related repositories

Introduction

telegram_media_downloader is a robust, cross-platform tool designed for efficiently downloading media files from Telegram conversations, chats, and channels. Based on Dineshkarthik's original project, it offers comprehensive support for various media types, including audio, video, documents, and photos, with individual file sizes up to 2GiB. This versatile downloader provides multiple interaction methods, including a user-friendly web interface and bot commands, making it accessible for different use cases. It also uniquely supports downloading resources from private groups that you have already joined, even if they have download restrictions.

Installation

Getting started with telegram_media_downloader is straightforward. Follow the instructions below based on your operating system or preferred deployment method.

For *nix OS distributions with make availability:

git clone https://github.com/tangyoha/telegram_media_downloader.git
cd telegram_media_downloader
make install

For Windows (without make inbuilt):

git clone https://github.com/tangyoha/telegram_media_downloader.git
cd telegram_media_downloader
pip3 install -r requirements.txt

Using Docker:

For a more detailed installation tutorial, refer to the official wiki. Ensure you have Docker and Docker Compose installed.

docker pull tangyoha/telegram_media_downloader:latest
mkdir -p ~/app && mkdir -p ~/app/log/ && cd ~/app
wget https://raw.githubusercontent.com/tangyoha/telegram_media_downloader/master/docker-compose.yaml -O docker-compose.yaml
wget https://raw.githubusercontent.com/tangyoha/telegram_media_downloader/master/config.yaml -O config.yaml
wget https://raw.githubusercontent.com/tangyoha/telegram_media_downloader/master/data.yaml -O data.yaml
# Edit config.yaml and docker-compose.yaml as needed
vi config.yaml

# First time setup: run in foreground to enter phone number and code
docker-compose run --rm telegram_media_downloader

# Subsequent startups can be in the background
docker-compose up -d

Upgrading:

cd telegram_media_downloader
pip3 install -r requirements.txt

Examples and Usage

telegram_media_downloader offers flexible ways to interact with it, whether through a web interface, bot commands, or direct execution.

Web Interface:

Once the application is running, you can access its web UI by opening a browser and navigating to localhost:5000. If running on a remote machine, ensure web_host: 0.0.0.0 is configured. The web interface provides a visual way to monitor download progress and manage settings.

Bot Commands:

For bot-driven downloads, you need to configure bot_token in your config.yaml. Refer to the documentation on how to download using robots for detailed instructions. You can then issue download or forward commands via the bot.

Configuration (config.yaml):

The core of the downloader's behavior is controlled by the config.yaml file. Key parameters include:

  • api_hash and api_id: Obtained from my.telegram.org/apps.
  • chat: A list of chat IDs to monitor, with options for last_read_message_id and download_filter (e.g., message_date >= 2022-12-01 00:00:00).
  • media_types: Specify which media types to download (e.g., audio, video, document).
  • save_path: The root directory for downloaded files.
  • upload_drive: Configuration for uploading files to cloud drives like Rclone or Aligo, including options for zipping and deleting after upload.
  • proxy: Support for socks4, socks5, and http proxies.

Here's a snippet of a typical config.yaml:

api_hash: your_api_hash
api_id: your_api_id
chat:
- chat_id: telegram_chat_id
  last_read_message_id: 0
  download_filter: message_date >= 2022-12-01 00:00:00 and message_date <= 2023-01-17 00:00:00
media_types:
- audio
- document
- photo
- video
save_path: D:\telegram_media_downloader
upload_drive:
  enable_upload_file: true
  remote_dir: drive:/telegram
  upload_adapter: rclone
  rclone_path: D:\rclone\rclone.exe
proxy:
  scheme: socks5
  hostname: 127.0.0.1
  port: 1234

Execution:

After configuring, simply run the script:

python3 media_downloader.py

Downloaded media will be organized within your save_path according to your file_path_prefix settings, which can include chat_title, media_datetime, and media_type.

Why Use telegram_media_downloader?

This tool stands out for several reasons:

  • Comprehensive Media Support: Downloads a wide range of media types, including audio, video, documents, photos, and voice messages.
  • Flexible Download Control: Utilize powerful filters based on message date to download specific content.
  • Multiple Interaction Methods: Choose between a convenient web UI, automated bot commands, or direct script execution.
  • Cloud Integration: Seamlessly upload downloaded files to various cloud storage providers via Rclone or Aligo, with options for zipping and post-upload deletion.
  • Cross-Platform Compatibility: Works across different operating systems, including *nix and Windows, with Docker support for easy deployment.
  • Customizable File Organization: Define how your downloaded files are structured and named using flexible prefix options.
  • Private Group Support: Download content from private groups you've joined, even if standard download options are restricted.

Links