iyear/tdl: a Telegram downloader and toolkit that ships as one Go binary

What tdl is for, and who actually needs it

tdl describes itself as a Telegram downloader, and the README adds the qualifier that it is more than a downloader. The feature list is the useful part: download files from protected chats, forward messages with automatic fallback and message routing, upload files to Telegram, and export messages, members or subscribers to JSON. Those four jobs share one property. They are all bulk operations against a chat you can already read.

The audience is therefore narrow and specific. Someone archiving a channel before it disappears. Someone moving a large media collection between chats without clicking through a desktop client. Someone who wants a subscriber list as JSON rather than as a screenshot. The README claims single file start-up, low resource usage, and that it takes up all your bandwidth, with a note that speed depends on whether the account is premium. That last clause matters more than the marketing around it: tdl is a client, and Telegram's own limits apply to whatever it does.

It is not a bot framework and it is not a replacement for the official apps. The topics list includes telegram-bot and telegram-userbot, but the README's own feature list is about moving data, not about building interactive services.

How tdl works: gotd, a local session, and command groups

The dependency list in go.mod is the clearest description of the architecture available. tdl builds on github.com/gotd/td, a Go client library for the Telegram MTProto API, with github.com/gotd/contrib alongside it. That means tdl speaks the same protocol as a normal client rather than the simpler HTTP Bot API. The practical consequence is that it can act as a user account, which is what makes protected chats and member exports possible at all.

The rest of the module graph reads like a CLI application assembled from parts. cobra and pflag for commands and flags, viper for configuration, zap for logging, go-pretty for terminal tables, survey for interactive prompts, go-qrcode for QR login, and bbolt for local storage. The repository layout confirms the split: cmd/ for commands, core/ for the engine, pkg/ for supporting packages, and extension/ as a separate module that is also released on its own version line, currently 0.20.4.

A session therefore lives on the machine where tdl runs, in a bbolt file, and the login step binds that session to a Telegram account. Everything after that is the account's own permissions applied through MTProto. There is no server component in the Dockerfile either: the image builds the binary and sets ENTRYPOINT to tdl, nothing else.

Building the tdl image and where the session lives

The README points at https://docs.iyear.me/tdl for documentation, and the repository carries a Dockerfile, so the container route is the one visible in the tree. The build stage is golang:1.25-alpine; the runtime stage is alpine:latest with ca-certificates added, and the entrypoint is the tdl binary. Build it from the repository root:

docker build -t tdl .

The build accepts VERSION, COMMIT and COMMIT_DATE as build arguments and injects them into github.com/iyear/tdl/pkg/consts, which is how the binary reports its own version. The Dockerfile does not declare a volume, and it does not document a configuration path, so the session location is something you confirm on your own machine rather than something the repository states.

The alternative build path is the Makefile, which wraps goreleaser:

make build

That target runs goreleaser build --rm-dist --single-target --snapshot and prints where the package lands. Building from source needs Go 1.25.8 per go.mod. Neither the Makefile nor the Dockerfile documents a login subcommand, a download flag or a default session directory, so the command surface has to come from tdl --help or from the documentation site. What you should see after a build is a single tdl binary, which is what the README means by single file start-up.

The limits tdl does not hide, and one it does

The README is honest about speed in a way most project pages are not. It says the tool reaches the proxy's speed limit and that speed depends on whether the account is premium. That is a real constraint, not a footnote: a non-premium account will be throttled by Telegram regardless of how many connections tdl opens. The claim that it takes up all your bandwidth is bounded by the account tier.

The second limit is structural. tdl authenticates as a user account through MTProto, which means every action is subject to that account's rate limits and, in the worst case, to Telegram's abuse systems. Bulk forwarding and bulk member export are exactly the patterns that attract attention. The README does not document rollback, does not describe what happens when a forward fails midway, and does not discuss account safety. That silence is the thing to weigh before running it against a large chat.

Third, the documentation lives on an external site while the repository README stays short. The README does not document the full command surface, and the release entries in the repository are version tags without changelog text. If you need to know whether a flag changed between v0.20.2 and v0.20.4, you are reading the source or the docs site.

Finally, the licence. AGPL-3.0 is a strong copyleft licence with a network clause. Running tdl locally is unremarkable, but embedding it in a service you expose to others is the case where the licence terms start to matter. That is a question for a lawyer, not for this article.

tdl versus the official Telegram clients and scripted Bot API tools

The obvious alternative is the official Telegram desktop client, which can download media from a chat and export data. The difference in approach is the interface. The official client is interactive and built for a person; tdl is a command line tool built for repetition and scripting. Downloading a channel's history through the desktop client means clicking through a chat and waiting. Doing it with tdl means one command and a file or JSON output you can process afterwards. The official client wins on safety and on being supported by Telegram itself.

The second alternative is anything built on the HTTP Bot API. A bot is easier to authorise, easier to revoke, and cannot touch chats it was not invited to. The trade-off runs the other way: a bot cannot read a protected chat it is not a member of, and it cannot export a member list the way a user account can. tdl's whole feature list depends on being a user, which is precisely why it can do those things and why it carries the risk that comes with them.

So the comparison is not about speed or polish. It is about identity. If a bot can do the job, use a bot. tdl exists for the cases where it cannot.

Maintenance, releases and what the version numbers tell you

The last push to the default branch was on 2026-09-21, and the repository is not archived. Recent releases are v0.20.4 on 2026-08-23, v0.20.3 on 2026-05-23 and v0.20.2 on 2026-03-28. That cadence, roughly every two to three months, is the practical upgrade cost: you are not tracking a fast-moving target, but you are also not getting weekly fixes.

The versioning has one quirk worth noting. go.mod requires github.com/iyear/tdl/core v0.20.4 and github.com/iyear/tdl/extension v0.20.4, matching the latest release tag. The extension is a separately versioned module, so an extension release and a binary release are not automatically the same thing. If you build from source, pin the module versions rather than the branch.

Building from source needs Go 1.25.8 per go.mod. The Makefile wraps goreleaser: make build produces a snapshot single-target build and prints where the package lands, and make packaging produces release artifacts without publishing. Because the runtime image is alpine with ca-certificates and nothing else, the container is small and the binary is the only moving part, which keeps upgrade work to pulling or rebuilding an image.

Editorial conclusion

Adopt tdl when you want one binary that logs in as a Telegram account and moves data in bulk, and you accept AGPL-3.0. Skip it if you need a hosted service or an official client replacement. Verify the login flow and session storage on your own machine before pointing it at a large archive.

Frequently asked questions

Official sources

1. iyear/tdl on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases