Download media files from a telegram conversation/chat/channel up to 2GiB per file
Download media files from a telegram conversation/chat/channel up to 2GiB per file
Download all media files from a conversation or a channel that you are a part of from telegram. A meta of last read/downloaded message is stored in the config file so that in such a way it won't download the same media file again.
| Category | Support |
|---|---|
| Language | Python 3.8 and above |
| Download media types | audio, document, photo, video, video_note, voice |
max_concurrent_downloads to limit simultaneous downloads and prevent Telegram bans.download_delay with support for fixed or random delays between downloading files.chats list in config.yaml.parallel_chats option to download from multiple chats concurrently using asyncio.gather.media_types, download_directory, start_date, and other filters locally for each specific chat without losing the ability to use global defaults.chat_id when relying on the default structure.last_read_message_id and retry states) completely separated for each chat.This version (3.0.0) contains breaking changes due to migration from Pyrogram to Telethon.
If you're upgrading from a previous version:
config.yaml and downloaded mediamake install to ensure all dependencies are properly installed⚠️ Important: We strongly recommend using
maketo ensure all dependencies are properly installed with correct Python version compatibility. By default,make installonly installs the minimal CLI dependencies.
For *nix OS distributions:
git clone https://github.com/Dineshkarthik/telegram_media_downloader.git
cd telegram_media_downloader
make installFor Windows or systems without make:
git clone https://github.com/Dineshkarthik/telegram_media_downloader.git
cd telegram_media_downloader
pip3 install -r requirements.txtIf you plan to use the graphical web interface, you must install the optional Web UI dependencies (requires Python 3.10+):
For *nix OS distributions:
make install_webuiFor Windows or systems without make:
pip3 install -r requirements-webui.txtNote: The
make installcommand automatically detects your Python version and installs the appropriate dependencies for optimal compatibility.
For contributors and developers who need additional development tools:
git clone https://github.com/Dineshkarthik/telegram_media_downloader.git
cd telegram_media_downloader
make dev_install # Installs both runtime and development dependenciesNote:
make dev_installalso automatically detects your Python version and installs version-specific development dependencies.
All the configurations are passed to the Telegram Media Downloader via config.yaml file.
config.yaml.example to config.yaml:cp config.yaml.example config.yamlconfig.yaml with your specific details (API keys, chat ID, etc.).Note:
config.yamlis ignored by git to prevent accidental commits of sensitive information. Always useconfig.yaml.exampleas the template.
Getting your API Keys: The very first step requires you to obtain a valid Telegram API key (API id/hash pair):
Getting chat id:
1. Using web telegram:
https://web.telegram.org/?legacy=1#/im?p=u853521067_2449618633394 here 853521067 is the chat id.https://web.telegram.org/?legacy=1#/im?p=@somename here somename is the chat id.https://web.telegram.org/?legacy=1#/im?p=s1301254321_6925449697188775560 here take 1301254321 and add -100 to the start of the id => -1001301254321.https://web.telegram.org/?legacy=1#/im?p=c1301254321_6925449697188775560 here take 1301254321 and add -100 to the start of the id => -1001301254321.2. Using bot:
…| Option | Description |
|---|---|
api_hash |
The api_hash you got from telegram apps |
api_id |
The api_id 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 media_types, download_directory, 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. |
last_read_message_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. |
ids_to_retry |
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. |
max_concurrent_downloads |
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. |
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 |
|---|---|---|---|
max_concurrent_downloads |
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)
max_concurrent_downloads: 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
max_concurrent_downloads: 8
download_delay: null
- chat_id: 987654321
# Falls back to global settings (2 concurrent, random 1–5 s delay)python3 media_downloader.pyNote: 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.pyThis 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.
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/<chat_id>/audio |
| document | path/to/project/<chat_id>/document |
| photo | path/to/project/<chat_id>/photo |
| video | path/to/project/<chat_id>/video |
| voice | path/to/project/<chat_id>/voice |
| voice_note | path/to/project/<chat_id>/voice_note |
You can specify a custom download directory by setting the download_directory option in your config.yaml. This allows you to organize all downloads in a single custom location while maintaining the media type subdirectories.
Examples:
download_directory: "/home/user/downloads/telegram" (absolute path)download_directory: "downloads/telegram" (relative path)download_directory: null (use default directory structure)If the specified directory doesn't exist, it will be automatically created. The media type subdirectories (audio/, photo/, etc.) will still be created within your custom directory.
socks4, socks5, http proxies are supported in this project currently. To use it, add the following to the bottom of your config.yaml file
proxy:
scheme: socks5
hostname: 11.22.33.44
port: 1234
username: your_username
password: your_passwordIf your proxy doesn’t require authorization you can omit username and password. Then the proxy will automatically be enabled.
Read through our [contributing guidelines](https://github.com/Dineshkarthik/telegram_media_downloader/blob/master/C
No open issues yet, or sync has not completed.