A type-safe Python SDK for TDL (Telegram Downloader). The package wraps the external tdl CLI binary with subprocess execution and exposes a Pydantic-powered Python API for login, chat export, download, upload, forward, backup, recover, migrate, and extension operations.

Other Languages: English | 繁體中文 | 简体中文

Features

• Python facade for the main tdl command groups.
• Pydantic option models for validation and CLI flag serialization.
• Enum types for common mode and output parameters.
• Structured TDLResult responses with stdout, stderr, and return code.
• Custom exceptions for missing binaries, command failures, and timeouts.

Requirements

• Python 3.11 or newer. CI currently validates Python 3.11, 3.12, and 3.13.
• The TDL CLI binary installed separately.

Install tdl first:

# macOS / Linux
curl -sSL https://docs.iyear.me/tdl/install.sh | bash

# or via Go
go install github.com/iyear/tdl@latest

Verify that the binary is available:

tdl version

Installation

pip install tdl-python-sdk

# or with uv
uv add tdl-python-sdk

Quick Start

from tdl_sdk import GlobalOptions, LoginOptions, LoginType, TDL

client = TDL(global_options=GlobalOptions(ns="my_session", proxy="socks5://127.0.0.1:1080"))

client.login(LoginOptions(login_type=LoginType.QR))

Use tdl_path when the binary is not on PATH:

from tdl_sdk import TDL

client = TDL(tdl_path="/usr/local/bin/tdl", timeout=600)

Common Usage

Login

TDL supports desktop, verification code, and QR login flows.

from tdl_sdk import LoginOptions, LoginType, TDL

client = TDL()

client.login(LoginOptions(login_type=LoginType.QR))
client.login(LoginOptions(login_type=LoginType.DESKTOP))
client.login(
    LoginOptions(
        login_type=LoginType.DESKTOP, desktop="/path/to/Telegram Desktop", passcode="your_passcode"
    )
)
client.login(LoginOptions(login_type=LoginType.CODE))

Chat

from tdl_sdk import (
    ChatExportOptions,
    ChatListOptions,
    ChatUsersOptions,
    ExportType,
    ListOutput,
    TDL,
)

client = TDL()

result = client.chat_ls(ChatListOptions(output=ListOutput.JSON, chat_filter="Type == 'channel'"))
print(result.stdout)

client.chat_export(
    ChatExportOptions(
        chat="my_channel",
        export_type=ExportType.LAST,
        export_input=[100],
        output="export.json",
        with_content=True,
    )
)

client.chat_users(ChatUsersOptions(chat="my_channel", output="users.json"))

Download

from tdl_sdk import DownloadOptions, TDL

client = TDL()

client.download(
    DownloadOptions(
        url=["https://t.me/channel/123", "https://t.me/channel/456"], download_dir="./downloads"
    )
)

client.download(
    DownloadOptions(
        file=["export.json"],
        download_dir="./media",
        include=["mp4", "mkv"],
        skip_same=True,
        takeout=True,
        template="{{ .DialogID }}_{{ .MessageID }}_{{ filenamify .FileName }}",
    )
)

client.download(DownloadOptions(file=["export.json"], serve=True, port=9090))

Upload

from tdl_sdk import TDL, UploadOptions

client = TDL()

client.upload(UploadOptions(path=["/data/video.mp4", "/data/photos/"]))
client.upload(UploadOptions(path=["./images/"], chat="my_channel", photo=True))
client.upload(UploadOptions(path=["./temp_files/"], chat="my_channel", rm=True))

Forward

from tdl_sdk import ForwardMode, ForwardOptions, TDL

client = TDL()

client.forward(
    ForwardOptions(forward_from=["https://t.me/source_channel/123"], to="target_channel")
)

client.forward(
    ForwardOptions(
        forward_from=["https://t.me/source/123", "export.json"],
        to="target_channel",
        mode=ForwardMode.CLONE,
        silent=True,
    )
)

result = client.forward(
    ForwardOptions(forward_from=["export.json"], to="target_channel", dry_run=True)
)
print(result.stdout)

Backup, Recover, And Migrate

from tdl_sdk import BackupOptions, MigrateOptions, RecoverOptions, TDL

client = TDL()

client.backup(BackupOptions(dst="./my_backup.tdl"))
client.recover(RecoverOptions(file="./my_backup.tdl"))
client.migrate(MigrateOptions(to={"type": "file", "path": "/new/storage"}))

Extensions

from tdl_sdk import ExtInstallOptions, TDL

client = TDL()

client.ext_install("github.com/user/tdl-ext-name")
client.ext_install("github.com/user/tdl-ext-name", ExtInstallOptions(force=True))

result = client.ext_list()
print(result.stdout)

client.ext_upgrade("ext-name")
client.ext_remove("ext-name")

Error Handling

from tdl_sdk import DownloadOptions, TDL
from tdl_sdk import TDLCommandError, TDLError, TDLNotFoundError, TDLTimeoutError

client = TDL(timeout=300)

try:
    client.download(DownloadOptions(url=["https://t.me/channel/123"]))
except TDLNotFoundError:
    print("tdl binary not found. Please install tdl first.")
except TDLTimeoutError as e:
    print(f"Command timed out: {e}")
except TDLCommandError as e:
    print(f"Command failed (exit code {e.return_code}): {e.stderr}")
except TDLError as e:
    print(f"Unexpected error: {e}")

Global Options

Global options are serialized before the command path and apply to every tdl command invoked by a client.

from tdl_sdk import GlobalOptions, TDL

client = TDL(
    global_options=GlobalOptions(
        ns="work_session",
        proxy="socks5://127.0.0.1:1080",
        threads=8,
        limit=4,
        pool=16,
        debug=True,
        reconnect_timeout="10m",
        storage={"type": "bolt", "path": "/custom/data"},
    ),
    tdl_path="/usr/local/bin/tdl",
    timeout=600,
)

Resources

• API documentation
• TDL upstream project
• Contributing guide

License

MIT