TGD

Download Telegram posts and media from direct links — one post or a range at a time.

Русский · Releases · Upstream project

---

What this is

TGD (TeleGram Downloader) is a small command-line client that downloads Telegram media and text posts to your computer. Give it a public post link, a t.me/c/ link for a chat your account can access, or an inclusive range:

https://t.me/example_channel/1001-1010

Downloaded content is grouped by chat under downloads/. TGD can also process a list from links.txt, apply delays between API requests, and write a detailed local log.

TGD does not bypass Telegram authentication or access controls. Your account must already have access to the requested chat and messages. Use it only for content you are entitled to download.

---

Quick start

1. Get TGD

Download the latest executable from Releases, or run it from source.

2. Create Telegram API credentials

Sign in at my.telegram.org, open API development tools, and create an application to obtain an api_id and api_hash.

3. Start the program

On the first run, TGD creates config.json interactively:

1. Enter your api_id and api_hash.
2. Choose whether to paste an existing Pyrogram session string.
3. If you do not have one, complete Telegram sign-in so TGD can generate it.

After login, paste a post link at the prompt. Type exit to finish.

Caution

config.json contains credentials and a reusable Telegram session string. Treat it like a password: never commit, publish, or send it to another person. The repository already ignores this file.

---

Supported links

Input	Example
Public post	https://t.me/example_channel/1423
Private/supergroup post	https://t.me/c/1234567890/10
Public inclusive range	https://t.me/example_channel/1001-1010
Private inclusive range	https://t.me/c/1234567890/101-120

The configured account must be able to open the target chat. Use canonical https://t.me/... links; malformed links are not handled gracefully in the current release.

Output

TGD creates one sanitized folder per chat:

downloads/
├── Example Channel/
│   ├── 1423_video.mp4
│   └── photo.jpg
└── Another Chat/
    └── -1234567890-27.txt

Recognized media includes audio, documents, photos, stickers, animations, videos, voice messages, and video notes. A message with no recognized media is saved as a UTF-8 .txt file. Captions are not written separately when a message contains media.

---

Configuration

The first run generates this structure in config.json:

{
  "api_id": "YOUR_API_ID",
  "api_hash": "YOUR_API_HASH",
  "session_string": "YOUR_SESSION_STRING",
  "settings": {
    "enable_links_auto_read": false,
    "logging": false,
    "wait_seconds": 0,
    "post_step": 1,
    "max_requests_per_second": 5,
    "random_delay_min": 1,
    "random_delay_max": 5
  }
}

Setting	Type	Default	Meaning
enable_links_auto_read	boolean	false	Process links.txt before opening the interactive prompt.
logging	boolean	false	Generate logging.conf and append diagnostics to app.log.
wait_seconds	number	0	Fixed pause between groups of messages.
post_step	integer	1	Messages processed before the fixed pause; minimum 1.
max_requests_per_second	number	5	Local rate limit; must be greater than 0.
random_delay_min	number	1	Minimum random pause before fetching each message.
random_delay_max	number	5	Maximum random pause; must not be lower than the minimum.

Higher delays can reduce request pressure, but do not guarantee that Telegram will not apply a flood-wait. Avoid aggressive values and comply with Telegram's terms and applicable limits.

Batch input with links.txt

Set enable_links_auto_read to true, create links.txt beside the executable, and put one link or range on each non-empty line:

https://t.me/example_channel/1423
https://t.me/c/1234567890/10
https://t.me/example_channel/1001-1010

TGD processes the file at startup and then keeps the interactive prompt open. links.txt is ignored by Git.

---

Logging and troubleshooting

Set logging to true to append runtime details to app.log. TGD generates logging.conf on first use; edit it to change Python logging levels and handlers. Both files are local and ignored by Git.

Symptom	What to check
config.json not found	Complete first-run setup, or place a valid config beside TGD.
Telegram login fails	Verify the API credentials, account access, and session string.
Chat or message is unavailable	Open the link with the same account and confirm the post still exists.
Requests are rate-limited	Reduce max_requests_per_second and/or increase the delays.
A link crashes	Check that it exactly matches one of the supported forms above.

Do not attach config.json to bug reports. Remove phone numbers, chat identifiers, usernames, file paths, and session-related data from logs before sharing them.

---

Running from source

Python 3.9 or newer is required.

git clone https://github.com/tavridabless/TGD.git
cd TGD
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python tgd.py

# Linux/macOS
source .venv/bin/activate
python -m pip install -r requirements.txt
python tgd.py

tgcrypto is included to accelerate Pyrogram's cryptographic operations.

Building a standalone executable

The convenience scripts install the dependencies and PyInstaller into the active environment, create a one-file console build, and remove intermediate files:

# Windows
.\build.bat

# Linux
./build.sh

Run them inside a disposable virtual environment. The result is tgd.exe on Windows or tgd on Linux; both are ignored by Git.

---

Project structure

TGD/
├── .github/FUNDING.yml
├── assets/
│   ├── post_wait.png
│   └── post_wait2.png
├── build.bat
├── build.sh
├── requirements.txt
├── tgd.py
└── utils.py

Runtime files such as config.json, links.txt, app.log, logging.conf, and downloads/ are intentionally not tracked.

Known limitations

• Link parsing expects a narrow canonical format and has limited validation.
• There is no resume database; rerunning a range can download the same messages again.
• File and sanitized chat-folder names can collide.
• Dependency versions are not pinned, so source builds are not fully reproducible.
• The project does not yet include automated tests or CI.
• No license file is included. Source availability alone does not grant redistribution or modification rights; clarify licensing with the authors before redistributing modified builds.

Privacy and responsible use

TGD operates through your personal Telegram session. Downloads, logs, link lists, and configuration can contain private information. Keep them out of source control, secure your workstation, and follow Telegram's terms, local law, and content owners' rights.

Credits

This repository contains the modified 1.4.M line maintained by tavridabless. TGD was originally created by bipinkrish and is built with Pyrogram.

Releases

• Modified releases
• Original upstream releases