tdl

English | 简体中文

📥 Telegram Downloader, but more than a downloader

Features

Single file start-up
Low resource usage
Take up all your bandwidth
Faster than official clients
Download files from (protected) chats
Upload files to Telegram

Preview

It reaches my proxy's speed limit, and the speed depends on whether you are a premium

Install

You can download prebuilt binaries from releases or install with below methods:

Linux & macOS

Install with Shell:

tdl will be installed to /usr/local/bin/tdl, and script also can be used to upgrade tdl.

# Install latest version
curl -sSL https://ghproxy.com/https://raw.githubusercontent.com/iyear/tdl/master/scripts/install.sh | sudo bash

# Use ghproxy.com to speed up download
curl -sSL https://ghproxy.com/https://raw.githubusercontent.com/iyear/tdl/master/scripts/install.sh | sudo bash -s -- --proxy
# Install specific version
curl -sSL https://ghproxy.com/https://raw.githubusercontent.com/iyear/tdl/master/scripts/install.sh | sudo bash -s -- --version VERSION

Install with package managers:

Make your contribution to package managers: File an issue

Windows

Install with PowerShell(Administrator):

tdl will be installed to $Env:SystemDrive\tdl(will be added to PATH), and script also can be used to upgrade tdl.

# Install latest version
iwr -useb https://ghproxy.com/https://raw.githubusercontent.com/iyear/tdl/master/scripts/install.ps1 | iex

# Use `ghproxy.com` to speed up download
$Script=iwr -useb https://ghproxy.com/https://raw.githubusercontent.com/iyear/tdl/master/scripts/install.ps1; $Block=[ScriptBlock]::Create($Script); Invoke-Command -ScriptBlock $Block -ArgumentList "", "$True"
# Install specific version
$Env:TDLVersion = "VERSION"
$Script=iwr -useb https://ghproxy.com/https://raw.githubusercontent.com/iyear/tdl/master/scripts/install.ps1; $Block=[ScriptBlock]::Create($Script); Invoke-Command -ScriptBlock $Block -ArgumentList "$Env:TDLVersion"

Install with package managers:

# Scoop (Windows) https://scoop.sh/#/apps?s=2&d=1&o=true&p=1&q=telegram+downloader
scoop bucket add extras
scoop install telegram-downloader

Quick Start

# login with existing official desktop clients (recommended)
tdl login -n quickstart
# if you set a local passcode
tdl login -n quickstart -p YOUR_PASSCODE
# specify custom path
tdl login -n quickstart -d /path/to/TelegramDesktop
# or login with phone & code
tdl login -n quickstart --code

tdl dl -n quickstart -u https://t.me/telegram/193

Workflows

Only show workflows, not all configs. So read Usage and set configs you need.

Download files from message urls

export TDL_NS=iyear # set our namespace
tdl login
tdl dl -u https://t.me/tdl/1 -u https://t.me/tdl/2

Download files from protected chats

export TDL_NS=iyear # set our namespace
tdl login
tdl chat export -o result.json
tdl dl -f result.json

Migrate data to remote server

export TDL_NS=iyear # set our namespace
tdl login
tdl backup -d backup.zip
# upload backup.zip to remote server
tdl recover -f backup.zip # run on remote server

Continuously downloading regardless of errors

It is recommended to use daemon program + tdl download, some errors may require reboot tdl to work properly.

tdl is not responsible for daemon, you can choose a daemon program for different platforms, for example systemd for Linux.

Command: tdl dl <OTHER_FLAGS> --continue

This way tdl will be restarted in case of errors and will continue downloading task sources.

Usage

Get help

tdl -h

Check the version

tdl version

Shell completion

Run corresponding command to enable shell completion in all sessions:

# bash
echo "source <(tdl completion bash)" >> ~/.bashrc
# zsh
echo "source <(tdl completion zsh)" >> ~/.zshrc
# fish
echo "tdl completion fish | source" >> ~/.config/fish/config.fish
# powershell
Add-Content -Path $PROFILE -Value "tdl completion powershell | Out-String | Invoke-Expression"

Basic Configs

The following command documents will not write basic configs. Please add the basic configs you need.

Each namespace represents a Telegram account

You should set the namespace when each command is executed:

tdl -n iyear
# or
export TDL_NS=iyear # recommended

(optional) Set the proxy. Only support socks now:

tdl --proxy socks5://localhost:1080
# or
export TDL_PROXY=socks5://localhost:1080 # recommended

(optional) Set ntp server host. If is empty, use system time:

tdl --ntp pool.ntp.org
# or
export TDL_NTP=pool.ntp.org # recommended

(optional) Set Telegram client reconnect timeout. Default is 2m:

Note Set higher timeout or 0(INF) if your network is poor.

tdl --reconnect-timeout 1m30s
# or
export TDL_RECONNECT_TIMEOUT=1m30s

Login

When you first use tdl, you need to login to get a Telegram session

If you have official desktop clients locally, you can import existing sessions.

This may reduce the risk of blocking, but is unproven:

tdl login
# if you set a local passcode
tdl login -p YOUR_PASSCODE
#  specify custom path
tdl login -d /path/to/TelegramDesktop

tdl login --code

Download

If you need higher speed, set higher threads. But do not arbitrarily set too large threads.

Download (protected) chat files from message urls:

tdl dl -u https://t.me/tdl/1 -u https://t.me/tdl/2

Download (protected) chat files from official desktop client exported JSON:

tdl dl -f result1.json -f result2.json

You can combine sources:

tdl dl \
-u https://t.me/tdl/1 -u https://t.me/tdl/2 \
-f result1.json -f result2.json

Download with 8 threads, 512KiB(MAX) part size, 4 concurrent tasks:

tdl dl -u https://t.me/tdl/1 -t 8 -s 524288 -l 4

Download with real extension according to MIME type:

Note If the file extension is not matched with the MIME type, tdl will rename the file with the correct extension.

Side effect: like .apk file, it will be renamed to .zip.

tdl dl -u https://t.me/tdl/1 --rewrite-ext

Skip the same files when downloading:

Note IF: file name(without extension) and size is the same

tdl dl -u https://t.me/tdl/1 --skip-same

Download files to custom directory:

tdl dl -u https://t.me/tdl/1 -d /path/to/dir

Download files with custom order:

Note Different order will affect resuming download

# download files in descending order(from newest to oldest)
tdl dl -f result.json --desc
# Default is ascending order
tdl dl -f result.json

Download files with takeout session:

Note If you plan to download a lot of media, you may prefer to do this within a takeout session. Takeout sessions let you export data from your account with lower flood wait limits.

tdl dl -u https://t.me/tdl/1 --takeout

Download files with extension filters:

Note The extension is only matched with the file name, not the MIME type. So it may not work as expected.

Whitelist and blacklist can not be used at the same time.

# whitelist filter, only download files with `.jpg` `.png` extension
tdl dl -u https://t.me/tdl/1 -i jpg,png

# blacklist filter, download all files except `.mp4` `.flv` extension
tdl dl -u https://t.me/tdl/1 -e mp4,flv

Download with custom file name template:

Please refer to template guide for more details.

tdl dl -u https://t.me/tdl/1 \
--template "{{ .DialogID }}_{{ .MessageID }}_{{ .DownloadDate }}_{{ .FileName }}"

Resume or restart download without UI interaction:

# resume
tdl dl -u https://t.me/tdl/1 --continue
# restart
tdl dl -u https://t.me/tdl/1 --restart

Full example:

tdl dl --debug --ntp pool.ntp.org \
-n iyear --proxy socks5://localhost:1080 \
-u https://t.me/tdl/1 -u https://t.me/tdl/2 \
-f result1.json -f result2.json \
--rewrite-ext --skip-same -i jpg,png \
-d /path/to/dir --desc \
-t 8 -s 262144 -l 4

Upload

Same instructions and advanced options as Download

Upload files to Saved Messages, exclude the specified file extensions:

tdl up -p /path/to/file -p /path/to/dir -e .so -e .tmp

Upload with 8 threads, 512KiB(MAX) part size, 4 concurrent tasks:

tdl up -p /path/to/file -t 8 -s 524288 -l 4

Delete the uploaded file after successful upload:

tdl up -p /path/to/file --rm

Upload to custom chat:

# chat input examples: `@iyear`, `iyear`, `123456789`(chat id), `https://t.me/iyear`, `+1 123456789`

# empty chat means `Saved Messages`
tdl up -p /path/to/file -c CHAT_INPUT

Full example:

tdl up --debug --ntp pool.ntp.org \
-n iyear --proxy socks5://localhost:1080 \
-p /path/to/file -p /path/to/dir \
-e .so -e .tmp \
-t 8 -s 262144 -l 4
-c @iyear

Migration

Backup or recover your data

Backup (Default: tdl-backup-<time>.zip):

tdl backup
# or specify the backup file path
tdl backup -d /path/to/backup.zip

Recover:

tdl recover -f /path/to/backup.zip

Chat Utilities

List all your chats:

tdl chat ls

# output with JSON format
tdl chat ls -o json

# specify filter that powered by expression engine, default is `true`(match all)
# feel free to file an issue if you have any questions about the expression engine.
# expression engine docs: https://expr.medv.io/docs/Language-Definition

# list all available filter fields
tdl chat ls -f -
# list channels that VisibleName contains "Telegram"
tdl chat ls -f "Type contains 'channel' && VisibleName contains 'Telegram'"
# list groups that have topics
tdl chat ls -f "len(Topics)>0"

Export JSON for tdl download:

# will export all media files in the chat.
# chat input examples: `@iyear`, `iyear`, `123456789`(chat id), `https://t.me/iyear`, `+1 123456789`

# export all media messages
tdl chat export -c CHAT_INPUT

# export all messages including non-media messages
tdl chat export -c CHAT_INPUT --all

# export Telegram MTProto raw message structure, useful for debugging
tdl chat export -c CHAT_INPUT --raw

# export from specific topic
# You can get topic id from:
# 1. message link: https://t.me/c/1492447836/251011/269724(251011 is topic id)
# 2. `tdl chat ls` command
tdl chat export -c CHAT_INPUT --topic TOPIC_ID
# export from specific channel post replies
tdl chat export -c CHAT_INPUT --reply MSG_ID

# export with specific timestamp range, default is start from 1970-01-01, end to now
tdl chat export -c CHAT_INPUT -i 1665700000,1665761624
# or (time is default type)
tdl chat export -c CHAT_INPUT -T time -i 1665700000,1665761624
# export with specific message id range, default to start from 0, end to latest message
tdl chat export -c CHAT_INPUT -T id -i 100,500
# export last N media files
tdl chat export -c CHAT_INPUT -T last -i 100 

# specify filter that powered by expression engine, default is `true`(match all)
# feel free to file an issue if you have any questions about the expression engine.
# expression engine docs: https://expr.medv.io/docs/Language-Definition

# list all available filter fields
tdl chat export -c CHAT_INPUT -f -
# match last 10 zip files that size > 5MiB and views > 200
tdl chat export -c CHAT_INPUT -T last -i 10 -f "Views>200 && Media.Name endsWith '.zip' && Media.Size > 5*1024*1024"

# specify the output file path, default is `tdl-export.json`
tdl chat export -c CHAT_INPUT -o /path/to/output.json

# export with message content
tdl chat export -c CHAT_INPUT --with-content

Env

Avoid typing the same flag values repeatedly every time by setting environment variables.

Note: The values of all environment variables have a lower priority than flags.

What flags mean: flags

NAME	FLAG
TDL_NS	`-n/--ns`
TDL_PROXY	`--proxy`
TDL_DEBUG	`--debug`
TDL_SIZE	`-s/--size`
TDL_THREADS	`-t/--threads`
TDL_LIMIT	`-l/--limit`
TDL_NTP	`--ntp`
TDL_RECONNECT_TIMEOUT	`--reconnect-timeout`
TDL_TEMPLATE	dl `--template`

Data

Your account information will be stored in the ~/.tdl directory.

Log files will be stored in the ~/.tdl/log directory.

Commands

Go to docs for full command docs.

Best Practice

How to minimize the risk of blocking?

Login with the official client session.
Use the default download and upload options as possible. Do not set too large threads and size.
Do not use the same account to login on multiple devices at the same time.
Don't download or upload too many files at once.
Become a Telegram premium user. 😅

Troubleshooting

Q: Why no response after entering the command? And why there is 'msg_id too high' in the log?

A: Check if you need to use a proxy (use proxy flag); Check if your system's local time is correct (use ntp flag or calibrate system time)

If that doesn't work, run again with --debug flag. Then file a new issue and paste your log in the issue.

Q: Desktop client stop working after using tdl?

A: If your desktop client can't receive messages, load chats, or send messages, you may encounter session conflicts.

You can try re-login with desktop client and select YES for logout, which will delete the session files to separate sessions.

Q: How to migrate session to another device?

A: You can use the tdl backup and tdl recover commands to export and import sessions. See Migration for more details.

FAQ

Q: Is this a form of abuse?

A: No. The download and upload speed is limited by the server side. Since the speed of official clients usually does not reach the account limit, this tool was developed to download files at the highest possible speed.

Q: Will this result in a ban?

A: I am not sure. All operations do not involve dangerous actions such as actively sending messages to other people. But it's safer to use a long-term account.

LICENSE

AGPL-3.0 License

iyear/tdl

iyear

Reviews

Repository Details

tdl

TOC