Telegram Media Downloader

Feature request · Report a bug · Support: Discussions & Telegram Community

Overview:

Support:

🎉 Version 3.4.0 - Interactive Web UI

What's New:

• Interactive Web UI: Added a sleek web-based interface for configuration and execution monitoring.

🎉 Version 3.3.0 - Download Pacing / Rate Limiting

What's New:

• Rate Limiting: Added maxconcurrentdownloads to limit simultaneous downloads and prevent Telegram bans.
• Download Delay: Added download_delay with support for fixed or random delays between downloading files.
• Improved Gentle Exit: The script safely remembers the last downloaded file when stopping.

🎉 Version 3.2.0 - Multi-Chat & Parallel Processing

What's New:

• Multiple Chats Support: Configure and download from multiple chats at once using a new chats list in config.yaml.
• Parallel Downloading: Added parallel_chats option to download from multiple chats concurrently using asyncio.gather.
• Per-Chat Configurations: Customize mediatypes, downloaddirectory, start_date, and other filters locally for each specific chat without losing the ability to use global defaults.
• Dynamic Directories: Downloaded media is automatically organized into subdirectories by chat_id when relying on the default structure.
• State Separation: Maintains tracking (lastreadmessage_id and retry states) completely separated for each chat.

⚠️ Version 3.0.0 - Breaking Changes

This version (3.0.0) contains breaking changes due to migration from Pyrogram to Telethon.

What's Changed:

• Backend Migration: Complete migration from Pyrogram to Telethon library
• API Changes: Some configuration options may have changed
• Dependencies: Updated to use Telethon-specific dependencies
• Python Requirement: Now requires Python 3.8 or higher (previously 3.7+)

Migration Guide:

• Backup your config.yaml and downloaded media
• Use make install to ensure all dependencies are properly installed
• Review your configuration as some options may have changed
• Test with a small channel first to verify everything works

Installation

⚠️ Important: We strongly recommend using make to ensure all dependencies are properly installed with correct Python version compatibility. By default, make install only installs the minimal CLI dependencies.

CLI-Only Installation (Recommended)

git clone https://github.com/Dineshkarthik/telegrammediadownloader.git
cd telegrammediadownloader
make install

For Windows or systems without make:

git clone https://github.com/Dineshkarthik/telegrammediadownloader.git cd telegrammediadownloader pip3 install -r requirements.txt

Web UI Installation

For *nix OS distributions:

make install_webui

For Windows or systems without make:

pip3 install -r requirements-webui.txt

Note: The make install command automatically detects your Python version and installs the appropriate dependencies for optimal compatibility.

Development Installation

For contributors and developers who need additional development tools:

git clone https://github.com/Dineshkarthik/telegrammediadownloader.git
cd telegrammediadownloader
make dev_install  # Installs both runtime and development dependencies

Note: make dev_install also automatically detects your Python version and installs version-specific development dependencies.

Configuration

All the configurations are passed to the Telegram Media Downloader via config.yaml file.

Setup Configuration

• Copy config.yaml.example to config.yaml:

cp config.yaml.example config.yaml

• Update the values in config.yaml with your specific details (API keys, chat ID, etc.).

Note: config.yaml is ignored by git to prevent accidental commits of sensitive information. Always use config.yaml.example as the template.

Getting your API Keys: The very first step requires you to obtain a valid Telegram API key (API id/hash pair):

• Visit https://my.telegram.org/apps and log in with your Telegram Account.
• Fill out the form to register a new Telegram application.
• Done! The API key consists of two parts: apiid and apihash.

Getting chat id:

1. Using web telegram:

• Open https://web.telegram.org/?legacy=1#/im
• Now go to the chat/channel and you will see the URL as something like

2. Using bot:

• Use @usernametoidbot to get the chatid of

config.yaml

apihash: yourapi_hash
apiid: yourapi_id
The downloader can process multiple chats (either sequentially or in parallel).
The 'chats' list is highly customizable per chat. If an option is not provided
in a chat dictionary, it will fall back to the global option defined above.
parallel_chats: false
chats:
  - chatid: telegramchatid1
    lastreadmessage_id: 0
    idstoretry: []
    # Local chat options map exactly as the globals (mediatypes, fileformats, etc.)
  - chatid: telegramchatid2
    lastreadmessage_id: 0
GLOBAL SETTINGS (act as fallback for local chats)
chatid: telegramchat_id
lastreadmessage_id: 0
idstoretry: []
media_types:
audio
document
photo
video
voice
video_note
file_formats:
  audio:
  - all
  document:
  - all
  video:
  - all
Optional filters (Can also be set in individual chats)
download_directory: null  # Custom directory path for downloads (absolute or relative path)
start_date: null  # Filter messages after this date (ISO format, e.g., '2023-01-01' or '2023-01-01T00:00:00')
end_date: null    # Filter messages before this date (ISO format)
max_messages: null  # Limit the number of media items to download (integer)
Download Pacing / Rate Limiting (optional, can also be set per-chat)
maxconcurrentdownloads: 4   # Max files downloading at once per batch (1 = fully sequential)
download_delay: null          # Delay between files: fixed (2) or random range ([1, 5])

| Option | Description | |---|---| | apihash | The apihash you got from telegram apps | | apiid | The apiid you got from telegram apps | | parallel_chats | If true, downloads chats inside the chats list concurrently. | | chats | A list of discrete chats/channels to download from. Setting mediatypes, downloaddirectory, etc., locally inside here overrides global options. | | chat_id | The id of the chat/channel you want to download media for. Can be set globally or locally. | | lastreadmessage_id | If it is the first time you are going to read the channel let it be 0 or if you have already used this script it will have auto-updated. | | idstoretry | Leave it as it is. This keeps track of all skipped downloads to retry. | | media_types | Type of media to download. | | file_formats | File types to download. Default is all. | | download_directory | Optional: Custom directory path where media files will be downloaded. Can be absolute or relative path. If null, uses default directory structure. | | start_date | Optional: Filter messages to download only those sent after this date (ISO format). Leave null to disable. | | end_date | Optional: Filter messages to download only those sent before this date (ISO format). Leave null to disable. | | max_messages | Optional: Limit the number of media items to download (integer). Leave null for unlimited. | | maxconcurrentdownloads | Optional: Maximum number of files downloading simultaneously per batch. Lower values reduce ban risk. 1 = fully sequential. Default: 4. | | download_delay | Optional: Pause between starting each file download (seconds). Use a number for a fixed delay (2) or a list for a random range ([1, 5]). Leave null for no delay. |

Download Pacing / Rate Limiting

To reduce the risk of Telegram rate-limiting or banning your account, you can slow down the downloader with two optional settings:

| Option | Type | Default | Description | |---|---|---|---| | maxconcurrentdownloads | int | 4 | Max files downloading simultaneously per batch. Set to 1 for fully sequential. | | download_delay | float \| [float, float] \| null | null | Pause between files. Fixed seconds (2) or random range ([1, 5]). |

Both options can be set globally or overridden per-chat:

# Global (applies to all chats unless overridden)
maxconcurrentdownloads: 2
download_delay: [1, 5]   # random 1–5 second pause between files
chats:   - chat_id: 123456789     # This chat downloads faster since it's a trusted source     maxconcurrentdownloads: 8     download_delay: null   - chat_id: 987654321     # Falls back to global settings (2 concurrent, random 1–5 s delay)

Execution

CLI Execution

python3 media_downloader.py

Web UI Execution

Note: The Web UI relies on NiceGUI and requires Python 3.10 or higher. It is an optional installation (see Web UI Installation).

For an interactive experience that lets you configure downloads, track progress visually, and view historical downloads within a built-in media player, you can start the built-in Web UI.

python3 webui.py

This will start a local web server (usually at http://127.0.0.1:8080).

📚 Click here to read the full Web UI Getting Started Guide to see screenshots of the Configuration, Execution, and History tabs.

Download Directories

By default, all downloaded media will be stored in respective directories named after the media type and scoped to their specific chat_id in the same path as the python script.

| Media type | Default Download directory | |--|--| | audio | path/to/project//audio | | document | path/to/project//document | | photo | path/to/project//photo | | video | path/to/project//video | | voice | path/to/project//voice | | voicenote | path/to/project/id>/voice_note |

proxy:
  scheme: socks5
  hostname: 11.22.33.44
  port: 1234
  username: your_username
  password: your_password