telegram_media_downloader: a self-hosted Telegram archiver with a web UI and a bot

What telegram_media_downloader actually archives

The project downloads media from Telegram conversations, chats and channels, up to 2GiB per file, according to the repository description. The README lists the supported media types as audio, document, photo, video, video_note and voice, and the sample config adds animation for GIFs. It is a Python 3.7 and above program, and setup.py classifies it as a console application for end users as well as developers.

The intended user is someone who has joined a chat and wants the files kept locally. That includes private groups where the client restricts saving or forwarding. The README states the tool supports downloading resources from private groups you have joined even when the group limits downloads. That is the main reason to pick this over clicking save in the Telegram client.

It is not a link resolver. Nothing in the README describes pasting a t.me URL and getting a file back, which is what several of the related searches (telegram media downloader by link, telegram media downloader online) are looking for. Authentication happens through your own Telegram account, so the tool sees what your account sees.

Two run modes: a Flask progress page and a bot command channel

The README describes two default ways to run it. In the first, the program starts, and you send the command download or forward from a Telegram bot. In the second, it runs as a one-time download tool driven by config.yaml.

When the web interface is enabled, the process serves a page on port 5000. The README says to open a browser at localhost:5000 after starting, and to set web_host to 0.0.0.0 if the machine is remote. The sample config keeps web_host at 127.0.0.1 and web_port at 5000, and includes a web_login_secret plus an allowed_user_ids list containing the string me, so the page is not open by default.

The bot path needs bot_token, and the README points to a wiki page for the setup. Download state is tracked per chat in config.yaml through last_read_message_id, and the README notes that ids_to_retry moved out of config.yaml into data.yaml. That split matters operationally: config.yaml is what you edit, data.yaml is what the program writes back. The docker-compose.yaml mounts both as separate files, so a container restart does not lose the retry list.

Installing telegram_media_downloader with make, pip or Docker

The README gives three install paths. On a Unix-like system with make available, clone the repository and run make install. On Windows, where make is not built in, install the requirements with pip3 instead. Both start the same way:

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

On Windows the second and third lines become `pip3 install -r requirements.txt`. Note what that file contains: the first line is not a PyPI package but a zip of a pyrogram fork hosted on GitHub, `https://github.com/tangyoha/pyrogram/archive/refs/heads/patch.zip`. Installation therefore depends on that repository staying reachable, and it pins PyYAML to 5.3.1 and flask to 2.2.2, both older releases.

The Docker route avoids the local Python version question. The README's sequence pulls the image, creates an app directory with a log subdirectory, downloads three files, and starts once in the foreground so you can enter your phone number and the login code:

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
vi config.yaml
docker-compose run --rm telegram_media_downloader

After the interactive login, `docker-compose up -d` starts it in the background. The compose file maps port 5000, mounts ./downloads/ into the container, and persists config.yaml, data.yaml, log/, sessions/ and temp/ from the host. The sessions directory is the one that holds the authenticated session, so back it up or you will repeat the phone login.

Before any of this, you need an API id and hash pair from https://my.telegram.org/apps, and at least one chat_id. The README explains both a web Telegram method and a bot method using @username_to_id_bot. The web method is the one with a trap: for a URL ending in `p=s1301254321_...` or `p=c1301254321_...`, you take the digits and prepend `-100`, producing an id like `-1001301254321`. Get that prefix wrong and the chat will not resolve.

The config that drives a first run looks like this:

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
- voice
save_path: D:\telegram_media_downloader
max_download_task: 5
web_host: 127.0.0.1
web_port: 5000

Setting last_read_message_id to 0 means the first pass walks the chat from the beginning, which is what you want for a full archive and what you do not want on a channel with years of video. The download_filter key takes a message_date expression, so you can bound that first pass by date instead. max_download_task: 5 caps concurrent downloads, and the README does not document what happens when you raise it.

Uploading to cloud storage through rclone

The sample config includes an upload_drive block with enable_upload_file, remote_dir, upload_adapter set to rclone, rclone_path, before_upload_file_zip and after_upload_file_delete. The Dockerfile installs rclone in the build stage and copies the binary to /app/rclone/rclone, which the comment says matches the code default, and docker-compose.yaml mounts $HOME/.config/rclone/ into the container so an existing rclone remote is visible.

This is the part of the project with the least documentation in the README. The keys are named and the defaults implied, but the README does not explain the interaction between before_upload_file_zip and after_upload_file_delete, and it does not describe what happens to a partially uploaded file. If you enable after_upload_file_delete, you are trusting an upload path whose failure handling is not described. Test it on a small chat before pointing it at an archive you care about.

Where telegram_media_downloader is the wrong tool

The single-file ceiling is 2GiB, per the repository description. Telegram itself enforces limits, and this project does not claim to work around them.

More importantly, this is account-based, not link-based. The tool logs in as you through api_id, api_hash and a session file. Anything your account cannot see, it cannot download, and the README's private-group claim is scoped to groups you have already joined. It is also not a client: there is no mobile app, no browser extension, and no hosted endpoint. The related searches for an apk, a Chrome extension, a Firefox add-on, a Tampermonkey script and a Greasyfork script all describe a different category of product. If that is what you want, this repository will not satisfy you.

There is also a maintenance signal worth reading carefully. The last push to the repository was on 2026-03-04, which is more than six months before today. The most recent tagged release listed is v2.2.5 from 2025-01-07, and before that v2.2.4 in July 2024. The README carries a version release plan pointing at issue 2 for v2.2.0. Commits and tags do not move at the same pace here, so pinning to a release tag gives you code that may be older than master.

How it differs from gallery-dl and from Telegram Desktop's export

The closest general-purpose alternative is gallery-dl, which supports many sites including Telegram and is driven by URL arguments and configuration files rather than a bot. The difference in approach is who initiates the work. gallery-dl is a command-line extractor you point at a target; telegram_media_downloader is a long-running service with a Flask page on port 5000 and a bot you message with download or forward. If you want a cron job with a URL argument, gallery-dl fits better. If you want to send a command from your phone and watch progress in a browser, this project is built for that.

Telegram Desktop's own export feature is the other comparison, and it is the honest baseline. It runs inside the client you already have, needs no API key, and produces JSON or HTML alongside the files. What it does not give you is a filter expression like `message_date >= 2022-12-01 00:00:00 and message_date <= 2023-01-17 00:00:00`, a retry list persisted in data.yaml, or an rclone upload step. The trade is convenience for repeatability.

Licence, upgrade cost and the questions to ask before adopting

The project is MIT licensed, per the repository metadata and the LICENSE file, and setup.py declares the same classifier. MIT is permissive: you can use, modify and redistribute it, including commercially, provided the copyright notice and permission notice are kept. That is a description of the licence text, not legal advice; if you are redistributing it inside a product, read the LICENSE file yourself.

The upgrade path in the README is short. For a source install, `cd telegram_media_downloader` then `pip3 install -r requirements.txt`. For Docker, pull the latest image, run `docker-compose down` in ~/app, then `docker-compose up -d`. Because data.yaml holds the retry state and sessions/ holds the login, both mounted from the host in the compose file, an image swap should not cost you either. What it can cost you is compatibility: requirements.txt pins flask 2.2.2, Werkzeug 2.2.2 and PyYAML 5.3.1, and installs pyrogram from a branch zip rather than a versioned release. A future Python release that drops any of those is a real upgrade risk, and the README does not document a rollback procedure if a new image breaks your setup.

The practical check before you adopt: run the interactive login once, point it at one small chat, and confirm the files land where save_path says. Then decide whether the bot or the web page is your primary interface, because the README treats them as two default modes rather than one workflow.

Editorial conclusion

Adopt it if you already run Docker or Python on a machine you control and you want a repeatable archive of named chats, including private groups you have joined, with a web page that shows progress. Do not adopt it if you want a one-click browser extension, an iPhone app, or a hosted service that takes a link and returns a file; this project has none of those, and the related searches asking for an apk, a Chrome extension or an online downloader describe products this repository does not ship. Before committing, verify three things on your own machine: that the patched pyrogram fork in requirements.txt installs against your Python version, that your api_id and api_hash work with the account you intend to use, and that your target chat's chat_id resolves to the negative -100 form the README describes for private channels. The last push to the repository was on 2026-03-04, so check the issue tracker for your platform before you build a workflow around it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tangyoha/telegram_media_downloader on GitHub