opentele-ng

Modern fork of thedemons/opentele. Python 3.10 – 3.14 • pure-Python runtime, no Qt dependency • reads current Telegram Desktop 5.x – 6.x tdata format • drop-in import opentele compatibility.

Why this fork

Upstream thedemons/opentele was last touched in 2022. By mid-2026 it stopped working on modern Python (3.13+ broke the metaclass), missed several lskType keys added to tdata in 2024-2025 (silently dropping data on read), shipped stale device fingerprints, and required ~50 MB of PyQt5 wheels just to parse binary streams.

opentele-ng is a clean-room modernization done over 11 release phases with 3-AI code review (OpenAI Codex, Cursor, Google Gemini) at every milestone. None of the 132 community forks of upstream attempted the pure-Python rewrite — this one ships it.

Highlights

Install

PyPI

pip install opentele-ng

from opentele.td import TDesktop
from opentele.tl import TelegramClient
from opentele.api import API, CreateNewSession

Runtime deps: telethon>=1.36,<2, tgcrypto-pyrofork>=1.2.7. No Qt.

System libraries (libgl1, libegl1, libxkbcommon-x11-0, etc.) are not required — you can deploy on Alpine, distroless, serverless, or any minimal Linux container.

Docker (v1.2.0+)

Multi-arch image at ghcr.io/stufently/opentele-ng (linux/amd64 + linux/arm64), ~140 MB, runs as non-root, opentele-ng is the entrypoint:

docker run --rm \
    -v "/path/to/Telegram/tdata:/tdata:ro" \
    ghcr.io/stufently/opentele-ng:latest info /tdata

See docs/examples/docker.md for batch / convert / air-gapped / Sigstore verification.

CLI — one-shot workflows (v1.1.0+)

# Read-only inspection of a tdata folder
opentele-ng info /path/to/Telegram/tdata

# Convert tdata → Telethon .session file
opentele-ng convert /path/to/Telegram/tdata --output ./me.session

See docs/examples/cli-quick-start.md for flags and exit codes.

Quick start (Python API)

import asyncio
from opentele.api import API, CreateNewSession
from opentele.td import TDesktop
from opentele.tl import TelegramClient

async def main() -> None:
    # 1. Load tdata produced by Telegram Desktop.
    tdata_path = r"C:\Users\<user>\AppData\Roaming\Telegram Desktop\tdata"
    tdesk = TDesktop(tdata_path)

    # 2. Pick an official API (TelegramIOS / TelegramAndroid / TelegramDesktop / TelegramMacOS).
    #    .Generate() builds a deterministic-or-random device fingerprint.
    api = API.TelegramIOS.Generate(unique_id="my-host")

    # 3. Convert TDesktop session → Telethon. CreateNewSession links a new
    #    device via QR code on the existing TDesktop session (no phone OTP).
    client: TelegramClient = await tdesk.ToTelethon(
        "new_session.session", CreateNewSession, api
    )

    async with client:
        await client.PrintSessions()

asyncio.run(main())

Examples

• docs/examples/qr-login.md — QR-code login flow with 2FA + **kwargs proxy forwarding.
• docs/examples/convert-tdata-to-telethon.md
• docs/examples/convert-telethon-to-tdata.md
• docs/examples/using-official-apis.md

Configuration

Status

• Latest: v1.3.2 (2026-07-29). PyPI: opentele-ng / Docker: ghcr.io/stufently/opentele-ng (Python 3.14). Production-ready. 1.3.2 fixes credential plumbing in TelegramClient.__init__ — the plain Telethon-style positional call TelegramClient(session, api_id, api_hash) silently set api_hash to the api_id, so login RPCs failed with ApiIdInvalidError (FromBundle hit the same bug) — and makes the coverage gate measure the whole package instead of ~55% of it. 1.3.1 added TelegramClient.FromBundle (authorized client from a JSON bundle + session file) and fully automatic releases (version bump on main → tag → PyPI + GHCR via autotag.yml). 1.3.0 closed 5 architectural known-issues from 1.2.2: kPerformanceMode default flipped to False so new tdata is actually encrypted (was using a hard-coded localKey), UTF-8 passcodes now work (was ASCII-only → crash), unknown lskType keys fail closed (was desyncing the stream), StorageAccount always reads/writes MTP config (was data-loss class in perf mode), and the Docker image now installs from a hash-locked deps file for reproducible builds.
• 305 tests on Python 3.10 / 3.11 / 3.12 / 3.13 / 3.14 (Docker matrix + GitHub Actions matrix × Ubuntu / macOS / Windows). 302 run and pass everywhere; 3 are opt-in and skip unless OPENTELE_REAL_TDATA_PATH points at a real tdata folder, and one more is version-gated to Python 3.13+.
• Coverage: 81.3% of the whole opentele package, CI gate 78%. Since 1.3.2 that is measured over all ~3165 statements — the pre-1.3.2 "84%" was computed over 1745, because .coveragerc excluded every raise / except / pass line and whole classes marked nocov. Core wire-format modules: td/storage.py 91%, td/qdatastream.py 89%, td/account.py 88%, td/mtp.py 87%.
• See CHANGELOG.md for the full per-release breakdown.

Security

opentele-ng accepts attacker-influenced binary blobs (tdata files from the filesystem), and version 1.0.3 added bounded-count guards on every loop that reads a count field from a decrypted payload. If you find a malformed tdata input that bypasses these guards or causes the library to read unbounded memory or CPU, please report it privately: see SECURITY.md.

Differences from upstream

• Import name unchanged (import opentele) — drop-in for code that already uses thedemons/opentele.
• PyPI dist name is opentele-ng to avoid collision with the original package.
• kMaxAccounts is 6 (Telegram's premium limit), not 3.
• @extend_class raises on attribute conflicts by default; set OPENTELE_EXTEND_STRICT=0 for the old warning-only behaviour.
• _settingsKey is FileKey(0) by default; the upstream FileKey(1851671142505648812) magic was removed in 1.0.1 (proper AES block padding added to Storage.PrepareEncrypted instead).
• PyQt6 is NOT a runtime dependency — opentele.td.qdatastream provides byte-compatible pure-Python replacements for QDataStream, QByteArray, QBuffer, QFile, QDir, QSysInfo.

Authorization

opentele-ng keeps the upstream's ability to use official APIs through the API class (API.TelegramDesktop, API.TelegramAndroid, API.TelegramAndroidX, API.TelegramIOS, API.TelegramMacOS, API.TelegramWeb_K, API.TelegramWeb_Z).

Per Telegram Terms of Service:

All accounts that sign up or log in using unofficial Telegram API clients are automatically put under observation to avoid violations of the Terms of Service.

Using an official API id/hash + lang_pack="tdesktop" (or ios, android, etc.) makes the session indistinguishable from the corresponding official client, which reduces spam-detection risk.

Credits

See ACKNOWLEDGMENTS.md.

License

MIT (same as upstream). See LICENSE.