telegram_media_downloader: a Telethon script for archiving chat media

What telegram_media_downloader actually archives

The README describes the scope plainly: download all media files from a conversation or a channel that you are a part of. That last clause is the whole product boundary. The tool authenticates as your Telegram account through Telethon, so it sees what your account sees. It is not a scraper for public links, and it does not bypass join requirements.

Six media types are listed in the support table: audio, document, photo, video, video_note and voice. The repository description adds the size ceiling, up to 2GiB per file. That ceiling is a Telegram limit rather than a design choice by the author, and it matters because a large video posted above it cannot be fetched by this path.

The intended user is someone who wants a local copy of a channel's history: a research archive, a backup of a group that may be deleted, or a personal media library. The README points feature requests and bug reports at GitHub Discussions and Issues, and there is a Telegram community channel, so the project expects a technically comfortable audience rather than a general consumer.

How the download loop and per-chat state work

The core mechanism is a stored cursor. The README states that a meta of the last read/downloaded message is stored in the config file so that it won't download the same media file again. Each run reads that cursor, walks forward through the chat, downloads matching media, and writes the new position back. Version 3.3.0 added an improved gentle exit that remembers the last downloaded file when stopping, which is what makes Ctrl+C safe rather than a way to lose your place.

Version 3.2.0 changed the shape of that state. A chats list in config.yaml lets you configure several chats at once, and parallel_chats downloads from them concurrently using asyncio.gather. Per-chat configuration can override media_types, download_directory and start_date locally while still inheriting global defaults. State separation is explicit: last_read_message_id and retry states are tracked independently per chat. When the default directory structure is used, media lands in subdirectories named by chat_id.

The backend is Telethon, not Pyrogram. The 3.0.0 release notes call this a complete migration with breaking changes and a Python floor of 3.8. Anyone reading an older tutorial that imports Pyrogram is reading about a version that no longer exists. There is also a db.py module in the repository tree, which suggests a database layer sits alongside the YAML cursor, but the README does not document its schema, so treat that file as something to inspect in the source before you rely on it.

Installing telegram_media_downloader and running a first download

The README recommends make over plain pip because make install detects your Python version and picks the matching requirements file. The Makefile confirms this: it computes PYTHON_VERSION, looks for requirements/requirements-<version>.txt, and falls back to requirements.txt only if that file is absent. The same pattern applies to dev and Web UI requirements files.

Clone the repository and run the install target:

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

On Windows or any system without make, the README gives the pip fallback, which installs the generic requirements.txt rather than a version-pinned file:

pip3 install -r requirements.txt

Before the first run you need credentials. Register an application at https://my.telegram.org/apps and note the api_id and api_hash pair. Then copy the example config, which is the only template the README endorses:

cp config.yaml.example config.yaml

Open config.yaml and fill in api_id, api_hash and your chat id. The README documents four ways to derive a chat id from a web.telegram.org URL. For a private chat URL of the form p=s1301254321_..., you take the digits and prefix -100, giving -1001301254321. A public channel URL of the form p=@somename gives somename directly. There is also a bot route, @username_to_id_bot, where you send a username or forward a message.

With config.yaml populated, run the downloader as a module:

python3 media_downloader.py

On a small test channel you should see progress output and files appearing under the configured download directory, organized by chat_id if you left the default structure. The config file is gitignored, so your keys and cursor stay out of version control. The Web UI is a separate install path: it needs Python 3.10 or newer and its own requirements file, installed with make install_webui.

Rate limiting, and why the tool ships its own throttle

Version 3.3.0 added max_concurrent_downloads to cap simultaneous downloads and download_delay to insert fixed or random pauses between files. The release note frames the first as a way to prevent Telegram bans. That is the honest reading of this feature: the tool can generate enough request volume that Telegram's own protections may respond, and the mitigation is client-side pacing.

This is a real operational constraint, not a footnote. If you archive a channel with tens of thousands of files, the default behavior may be too aggressive for your account, and tuning max_concurrent_downloads and download_delay becomes part of the setup rather than an afterthought. The README does not publish recommended values, so the numbers you choose are yours to find. Start conservative on a small channel and watch for throttling before you commit a large job.

The gentle exit feature belongs to the same release and addresses a different failure: a long archive interrupted halfway. Because the cursor is written to config.yaml, a restart resumes rather than re-downloading. That combination, pacing plus resumable state, is the strongest part of the design for large jobs.

Where telegram_media_downloader is the wrong tool

The most common mismatch is expectation. Search results for this project's name include phrases like telegram media downloader extension, tampermonkey, chrome extension, apk and online. None of those describe this project. It is a Python script that runs on your machine with your API credentials. There is no browser extension, no Android package, no hosted web service, and no iPhone app in the repository. A Web UI exists from version 3.4.0, but the README describes it as a local interface for configuration and execution monitoring, not a public download site.

The second mismatch is access. The README's own framing is media from a conversation or channel that you are a part of. Questions about downloading restricted photos or saving restricted videos describe a different problem: content your account cannot reach. This tool does not solve that, and nothing in the README suggests it tries.

The third is scale and hardware. Files up to 2GiB per item, downloaded sequentially or in a small parallel pool, accumulate quickly. A full channel archive can consume substantial disk and hours of wall time. If you need a one-off download of a single video, cloning a repository, registering a Telegram application and editing YAML is considerably more work than the task warrants.

Alternatives and how they differ in approach

The nearest alternative in the same category is gallery-dl, which supports Telegram among many other sites. The difference in approach is breadth versus depth. gallery-dl is a general-purpose extractor with a large set of site adapters and a configuration model built around that generality. telegram_media_downloader does one platform and spends its configuration surface on Telegram-specific concerns: per-chat overrides, chat_id subdirectories, a last_read_message_id cursor per chat, and download pacing tuned to Telegram's limits. If Telegram is your only target and you want the cursor and multi-chat behavior built in, this project is the more direct fit. If you also archive from other sites and prefer one tool, gallery-dl avoids running two systems.

A second option is writing against Telethon directly. This project is essentially a maintained wrapper around that library, and the 3.0.0 migration shows how much churn the underlying API can produce. Using Telethon yourself means owning that churn but also getting exactly the filtering and storage layout you want. The trade-off is that you reimplement the resumable cursor and the rate limiting that versions 3.2.0 and 3.3.0 already provide.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-04-27. Releases moved quickly in early 2026: v3.2.0 on 2026-02-22, v3.3.0 on 2026-02-23, and v3.4.0 on 2026-02-24. That cadence suggests active work, but the README does not document a support window or a deprecation policy, so you cannot infer how long a given config format will survive.

The upgrade history is the practical warning. Version 3.0.0 was a breaking release because the backend moved from Pyrogram to Telethon, and the README's migration guide tells users to back up config.yaml and downloaded media, run make install, review the configuration, and test on a small channel first. That is the cost profile of this project: occasional breaking changes that require you to re-check your config against config.yaml.example.

Licensing is MIT, per the LICENSE file and the setup.py classifier. MIT is permissive and places few obligations on how you use or redistribute the code. That is a statement about the license text, not legal advice; if you plan to redistribute the tool or bundle it into a product, read the LICENSE file and the terms you accepted at my.telegram.org, since your API credentials carry their own conditions.

Editorial conclusion

Adopt it if you already have Python 3.8 or newer, can register an app at my.telegram.org, and want a repeatable CLI job that keeps per-chat progress in config.yaml. Do not adopt it if you need a browser extension, an APK, a hosted online service, or a way into chats your account has not joined; the project is a local script, not a service. Verify first that your Python version matches the requirements file the Makefile selects, that make install resolves the right requirements-<version>.txt, and that a small test channel downloads and resumes as expected before you point it at a large archive.

Frequently asked questions

Official sources

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