This release is a pre-release and may not be stable for production use.
Pytdbot
Pytdbot is an asynchronous TDLib wrapper for Telegram users/bots written in Python.
Features
Pytdbot offers numerous advantages, including:
- Easy to Use: Designed with simplicity in mind, making it accessible for developers
- Performance: Fast and powerful, making it ready to fight
- Asynchronous: Fully asynchronous that allows for non-blocking requests and improved responsiveness
- Scalable: Easily scalable using TDLib Server
- Well-typed: Provides clear and well-defined methods and types to enhance developer experience
- Decorator-Based Updates: Simplifies the implementation of update handlers through a decorator pattern
- Bound Methods: Features types bound methods for improved usability
- Unlimited Support: Supports Plugins, filters, TDLib types/functions and much more
Requirements
Installation
For better performance, it's recommended to install orjson or ujson.
You can install Pytdbot with TDLib included using pip:
pip install --upgrade pytdbot[tdjson]
If the installation fails, then install without pre-built TDLib:
pip install pytdbot
Then you need to build TDLib from source and pass it to Client.lib_path.
You could also install the development version using the following command:
pip install --pre pytdbot
Examples
Basic example:
import asyncio
import logging
from pytdbot import Client, types
logging.basicConfig(
level=logging.INFO,
format="[%(levelname)s][p %(process)d %(threadName)s][%(created)f][%(filename)s:%(lineno)d][%(funcName)s][%(name)s] %(message)s",
)
client = Client(
token="1088394097:AAQX2DnWiw4ihwiJUhIHOGog8gGOI", # Your bot token
api_id=0,
api_hash="API_HASH",
files_directory="BotDB", # Path where to store TDLib files
database_encryption_key="1234echobot$",
td_verbosity=2, # TDLib verbosity level
td_log=types.LogStreamFile("tdlib.log", 104857600), # Set TDLib log file path
)
@client.on_updateNewMessage()
async def print_message(c: Client, message: types.UpdateNewMessage):
print(message)
@client.on_message()
async def say_hello(c: Client, message: types.Message):
msg = await message.reply_text(f"Hey {await message.mention(parse_mode='html')}! I'm cooking up a surprise... 🍳👨🍳", parse_mode="html")
async with message.action("choose_sticker"):
await asyncio.sleep(5)
await msg.edit_text("Boo! 👻 Just kidding.")
# Run the client
asyncio.run(client.run())
For more examples, check the examples folder.
Using AI agents
Pytdbot includes a skill and a local docs CLI so coding agents can use the library correctly (bound methods, helpers, TDLib types, and so on)
- Install Pytdbot
- Point your agent at the skill file:
- In this repo:
pytdbot/ai/SKILL.md - or using:
curl -O "https://raw.githubusercontent.com/pytdbot/client/refs/heads/main/pytdbot/ai/SKILL.md"
- In this repo:
- Register it the way your tool expects (project skill, agent rule, or “read this file first”)
The skill explains how Pytdbot is meant to be used; the CLI returns live signatures from your installed version.
Thanks to
-
You for viewing or using this project.
-
@levlam for maintaining TDLib and for the help to create Pytdbot.
License
MIT License
1 maintainer
Metadata
1 maintainer
Release files for Pytdbot 1.0.0b1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pytdbot-1.0.0b1.tar.gz | 867.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pytdbot-1.0.0b1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.8 MB
Release files / pytdbot-1.0.0b1.tar.gz
| Download URL | pytdbot-1.0.0b1.tar.gz |
|---|---|
| Size | 867.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
26dc773a4db3746ed73c419bebe110274b5276604b5bd2888d15cabd7a6b4277
|
|
BLAKE2b-256 checksum How to use checksums |
1651571523b45246dc4dc2e36a57134f8710980d14b9a8c69a58d075d583cee3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency logRelease files / pytdbot-1.0.0b1-py3-none-any.whl
| Download URL | pytdbot-1.0.0b1-py3-none-any.whl |
|---|---|
| Size | 884.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bcdf5826302e5066d351ebb56e9b55341b279dd37eda524c14e69ebcd8b4a199
|
|
BLAKE2b-256 checksum How to use checksums |
bcc97c086b0b3fb4f39e3ff3eb30a4120be60cc5be7809bd81a6eb3d124c0a46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.
Transparency log
