python-telegram

Build Status PyPI Read the Docs

Python API for the tdlib library. It helps you build your own Telegram clients.

tdlib connects to Telegram over MTProto, the same protocol the official apps use. This library signs in as a full Telegram account with a phone number, and it can do what a regular client can do.

It is not a wrapper around the HTTP Bot API. If you only need a bot, python-telegram-bot is a better fit. You can still sign in as a bot here by passing bot_token instead of phone.

Installation

This library requires Python 3.10+. Windows is not supported.

pip install python-telegram

See documentation for more details.

tdlib

Four wheels bundle a tdlib binary. Each one works on Python 3.10 through 3.14:

Platform Wheel Needs at least
Linux x86_64 manylinux_2_28_x86_64 glibc 2.28
Linux aarch64 manylinux_2_28_aarch64 glibc 2.28
macOS arm64 macosx_11_0_arm64 macOS 11
macOS x86_64 macosx_10_15_x86_64 macOS 10.15

Those binaries link OpenSSL and zlib statically, so they need nothing from the system.

Anywhere else, pip installs the source distribution, which carries no binary. On musl, on 32-bit ARM, or with an older glibc, compile tdlib yourself.

python-telegram looks for the library in this order, and logs which one it used:

  1. the library_path argument
  2. the PYTHON_TELEGRAM_TDLIB_PATH environment variable
  3. a system-wide tdjson
  4. the bundled binary

A system-wide tdlib therefore wins over the bundled one. To point at a specific build, pass its path. The file is called libtdjson.so on Linux and libtdjson.dylib on macOS:

tg = Telegram(
    # ...
    library_path="/usr/local/lib/libtdjson.so",
)

If nothing can be found, TDJson() raises TDLibNotFoundError, an OSError subclass whose message names the platform, the paths tried and the overrides.

Docker

This library has a docker image:

docker run -i -t --rm \
            -v /tmp/docker-python-telegram/:/tmp/ \
            akhmetov/python-telegram \
            python3 /app/examples/send_message.py $API_ID $API_HASH $PHONE $CHAT_ID $TEXT

How to use the library

First, register a new Telegram application to get your api_id and api_hash. Check out the tutorial for more details.

Basic example:

from telegram.client import Telegram
from telegram.text import Spoiler

tg = Telegram(
    api_id=123456,
    api_hash="api_hash",
    phone="+31611111111",  # you can pass 'bot_token' instead
    database_encryption_key="changekey123",
    files_directory="/tmp/.tdlib_files/",
)
tg.login()

# The chat must be in the tdlib database before you can send a message to it.
# `get_chats` loads up to `limit` chats from the main chat list.
result = tg.get_chats(limit=100)
result.wait()

chat_id = 123456789
result = tg.send_message(chat_id, Spoiler("Hello world!"))

# `tdlib` is asynchronous, so `python-telegram` always returns an `AsyncResult` object.
# You can receive a result with the `wait` method of this object.
result.wait()
print(result.update)

tg.stop()  # You must call `stop` at the end of the script.

You can also use call_method to call any tdlib method:

tg.call_method("getUser", params={"user_id": user_id})

More examples can be found in the /examples/ directory.

More information is available in the documentation.

Development

See CONTRIBUTING.md.

Project links

Data verified by PyPI on Aug 23, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for akhmetov from gravatar.com akhmetov

Credits

Author: Alexander Akhmetov

GitHub Statistics

Data verified by PyPI on Aug 23, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Tags

api client td tdjson tdlib telegram

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_telegram-2.0.0.tar.gz (26.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

python_telegram-2.0.0-py3-none-manylinux_2_28_x86_64.whl (15.8 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

python_telegram-2.0.0-py3-none-manylinux_2_28_aarch64.whl (15.6 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

python_telegram-2.0.0-py3-none-macosx_11_0_arm64.whl (10.6 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

python_telegram-2.0.0-py3-none-macosx_10_15_x86_64.whl (11.5 MB view details)

Uploaded Python 3macOS 10.15+ x86-64

File details

Details for the file python_telegram-2.0.0.tar.gz.

File metadata

  • Download URL: python_telegram-2.0.0.tar.gz
  • Upload date:
  • Size: 26.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for python_telegram-2.0.0.tar.gz
Algorithm Hash digest
SHA256 5e024306fdb1c633ed2ab02981f3d36bca73d759cf776e3940f36babbc999002
MD5 4778a65c8f95ef3e913d96fbb588ddde
BLAKE2b-256 6d61310fe14c1e6700940d2bb4c79d7cb91e256fa4c02c148b4646924b70c42a

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_telegram-2.0.0.tar.gz:

Publisher: release.yml on alexander-akhmetov/python-telegram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_telegram-2.0.0-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for python_telegram-2.0.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 36f7264be8eb6a9ec727d6ea78ca4b9828aaad491995eb5cb91aa24b76d1ef19
MD5 ec42fc01072d0e8dcb0e9a6ec038cdf2
BLAKE2b-256 21ac0963c95583dfee246e5364b50980d799c59d0d148f27d4d5587aa1df7021

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_telegram-2.0.0-py3-none-manylinux_2_28_x86_64.whl:

Publisher: release.yml on alexander-akhmetov/python-telegram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_telegram-2.0.0-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for python_telegram-2.0.0-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 7edd4367fa1a597a654e38c86c964494629fb6d03f4cb2d7ba4a7193b6847e30
MD5 05faaec8ae9d8b66f14065fc73ceea72
BLAKE2b-256 4032c294e26bc0d48d818fe192af3ae415a86a79924d67cdeee62c0d229da77e

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_telegram-2.0.0-py3-none-manylinux_2_28_aarch64.whl:

Publisher: release.yml on alexander-akhmetov/python-telegram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_telegram-2.0.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for python_telegram-2.0.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 67491bc97235cc93165068aa2f37b5eeb53206bdeb64cd0020c1f21fb951caed
MD5 15d35946ec18a1ba310978c6b9c6b436
BLAKE2b-256 525e91858b231e4383c6a5d207b9458ff1e2ebdffd4a84f09b09ff9d3dd7d10d

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_telegram-2.0.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on alexander-akhmetov/python-telegram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_telegram-2.0.0-py3-none-macosx_10_15_x86_64.whl.

File metadata

File hashes

Hashes for python_telegram-2.0.0-py3-none-macosx_10_15_x86_64.whl
Algorithm Hash digest
SHA256 0abaea7a48e494260c384490d1fa5938ab838dfa285a97098440a8f3dc469e55
MD5 c64224d3c8f75737f35044affc7328a1
BLAKE2b-256 960ae1dd574af0ec1cb0f29a4aaa1e7de0ab7eb10d9befddc5076aa6ff2d1333

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_telegram-2.0.0-py3-none-macosx_10_15_x86_64.whl:

Publisher: release.yml on alexander-akhmetov/python-telegram

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.0.0 This release

5 files

0.19.0

2 files

0.18.0

1 file

0.17.0

1 file

0.16.0

1 file

0.15.0

1 file

0.14.0

1 file

0.13.0

1 file

0.12.0

1 file

0.11.0

1 file

0.10.0

1 file

0.9.0

1 file

0.8.0

1 file

0.7.0

1 file

0.6.1

1 file

0.6.0

1 file

0.5.0

1 file

0.4.0

1 file

0.3.1

1 file

0.3.0

1 file

0.2.0

1 file

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page