[opensourcedex]

python-telegram-bot is a free, open source ai interaction & interfaces project written in Python and released under GPL-3.0. It has 29,468 GitHub stars, 6,148 forks and 31 open issues, and was last pushed 11 hours ago. On this registry it ranks #23 of 76 tracked projects in AI Interaction & Interfaces, with 5 head-to-head comparisons available. It gained 1 stars over the last 3 tracked days.

What is python-telegram-bot?

What it is

python-telegram-bot is a pure Python, asynchronous wrapper around the Telegram Bot API, distributed as the python-telegram-bot package on PyPI and developed in the open under the copyright-holder's GPL listing. It lives in the Python ecosystem and targets Python 3.10 and newer. The repository carries the topics bot, chatbot, framework, python and telegram, and the project has been maintained for roughly eleven years. Its tagline, "We have made you a wrapper you can't refuse", is the project's own framing of the role it plays: a library that sits between a Python program and Telegram's servers.

The concrete problem it solves is the tedium of talking to the Bot API by hand. Without such a wrapper, a developer has to build HTTP requests, manage serialization of every type and method, and handle asynchronous plumbing for each update. This library provides the API implementation itself, and on top of it the telegram.ext submodule supplies high-level classes and convenience shortcuts that make bot development straightforward. All types and methods of Telegram Bot API 10.0 are natively supported, and Bot API functionality not yet natively included can still be reached through the approach documented in the project wiki.

Key capabilities

  • Fully asynchronous interface to the Telegram Bot API.
  • Native coverage of all types and methods in Telegram Bot API 10.0.
  • Convenience shortcut methods, such as Message.reply_text.
  • Static type hints applied throughout, so the library is fully annotated.
  • A customizable and extendable interface for adapting behavior.
  • Seamless integration with both webhooks and polling.
  • Comprehensive documentation and examples shipped alongside the code.

Who uses it and how

  • Developers building Telegram bots that handle updates through long polling in a running Python process.
  • Teams deploying bots behind webhooks, where Telegram pushes updates to a reachable endpoint instead of the bot polling.
  • Maintainers of larger bots that lean on telegram.ext high-level classes to structure handlers and application logic.
  • Projects that need an API method or type not yet natively wrapped, using the wiki approach to reach it from the same codebase.
  • Contributors and users who take part in the project's Telegram group and follow releases through its Telegram channel.

Getting started

Install or upgrade from PyPI with pip install python-telegram-bot --upgrade, adding the --pre flag for a pre-release. Building from source is also supported: clone the repository, install the build tool, and run python -m build.

When to use it — and when

project readme (upstream, from github) — read inline

.. image:: https://raw.githubusercontent.com/python-telegram-bot/logos/master/logo-text/png/ptb-logo-text_768.png :align: center :target: https://python-telegram-bot.org :alt: python-telegram-bot Logo

.. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg :target: https://pypi.org/project/python-telegram-bot/ :alt: PyPi Package Version

.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg :target: https://pypi.org/project/python-telegram-bot/ :alt: Supported Python versions

.. image:: https://img.shields.io/badge/Bot%20API-10.0-blue?logo=telegram :target: https://core.telegram.org/bots/api-changelog :alt: Supported Bot API version

.. image:: https://img.shields.io/pypi/dm/python-telegram-bot :target: https://pypistats.org/packages/python-telegram-bot :alt: PyPi Package Monthly Download

.. image:: https://app.readthedocs.org/projects/python-telegram-bot/badge/?version=stable :target: https://docs.python-telegram-bot.org/en/stable/ :alt: Documentation Status

.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg :target: https://www.gnu.org/licenses/lgpl-3.0.html :alt: LGPLv3 License

.. image:: https://github.com/python-telegram-bot/python-telegram-bot/actions/workflows/unit_tests.yml/badge.svg?branch=master :target: https://github.com/python-telegram-bot/python-telegram-bot/ :alt: Github Actions workflow

.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: Code coverage

.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot :alt: Median time to resolve an issue

.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968 :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard :alt: Code quality: Codacy

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black :alt: Code Style: Black

.. image:: https://img.shields.io/badge/Telegram-Channel-blue.svg?logo=telegram :target: https://t.me/pythontelegrambotchannel :alt: Telegram Channel

.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram :target: https://telegram.me/pythontelegrambotgroup :alt: Telegram Group

We have made you a wrapper you can't refuse

We have a vibrant community of developers helping each other in our Telegram group _. Join us!

Stay tuned for library updates and new releases on our Telegram Channel _.

Introduction

This library provides a pure Python, asynchronous interface for the Telegram Bot API _. It's compatible with Python versions 3.10+.

In addition to the pure API implementation, this library features several convenience methods and shortcuts as well as a number of high-level classes to make the development of bots easy and straightforward. These classes are contained in the telegram.ext submodule.

After installing_ the library, be sure to check out the section on working with PTB_.

Telegram API support


All types and methods of the Telegram Bot API **10.0** are natively supported by this library.
In addition, Bot API functionality not yet natively included can still be used as described `in our wiki `_.

Notable Features
~~~~~~~~~~~~~~~~

- `Fully asynchronous `_
- Convenient shortcut methods, e.g. `Message.reply_text `_
- `Fully annotated with static type hints `_
- `Customizable and extendable interface `_
- Seamless integration with `webhooks `_ and `polling `_
- `Comprehensive documentation and examples `_

Installing
----------

You can install or upgrade ``python-telegram-bot`` via

.. code:: shell

    $ pip install python-telegram-bot --upgrade

To install a pre-release, use the ``--pre`` `flag `_ in addition.

You can also install ``python-telegram-bot`` from source, though this is usually not necessary.

.. code:: shell

    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
    $ cd python-telegram-bot
    $ pip install build
    $ python -m build

You can also use your favored package manager (such as ``uv``, ``hatch``, ``poetry``, etc.) instead of ``pip``.

Verifying Releases
~~~~~~~~~~~~~~~~~~

To enable you to verify that a release file that you downloaded was indeed provided by the ``python-telegram-bot`` team, we have taken the following measures.

Starting with v21.4, all releases are signed via `sigstore `_.
The corresponding signature files are uploaded to the `GitHub releases page`_.
To verify the signature, please install the `sigstore Python client `_ and follow the instructions for `verifying signatures from GitHub Actions `_. As input for the ``--repository`` parameter, please use the value ``python-telegram-bot/python-telegram-bot``.

Earlier releases are signed with a GPG key.
The signatures are uploaded to both the `GitHub releases page`_ and the `PyPI project `_ and end with a suffix ``.asc``.
Please find the public keys `here `_.
The keys are named in the format ``-.gpg``.

In addition, the GitHub release page also contains the sha1 hashes of the release files in the files with the suffix ``.sha1``.

Dependencies & Their Versions

python-telegram-bot tries to use as few 3rd party dependencies as possible. However, for some features using a 3rd party library is more sane than implementing the functionality again. As these features are optional, the corresponding 3rd party dependencies are not installed by default. Instead, they are listed as optional dependencies. This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.

The only required dependency is httpx >=0.27,_ for telegram.request.HTTPXRequest, the default networking backend.

python-telegram-bot is most useful when used along with additional libraries. To minimize dependency conflicts, we try to be liberal in terms of version requirements on the (optional) dependencies. On the other hand, we have to ensure stability of python-telegram-bot, which is why we do apply version bounds. If you encounter dependency conflicts due to these bounds, feel free to reach out.

Optional Dependencies #####################

PTB can be installed with optional dependencies:

  • pip install "python-telegram-bot[passport]" installs the cryptography>=39.0.1 _ library. Use this, if you want to use Telegram Passport related functionality.
  • pip install "python-telegram-bot[socks]" installs httpx[socks] _. Use this, if you want to work behind a Socks5 server.
  • pip install "python-telegram-bot[http2]" installs httpx[http2] _. Use this, if you want to use HTTP/2.
  • pip install "python-telegram-bot[rate-limiter]" installs aiolimiter~=1.1,_. Use this, if you want to use telegram.ext.AIORateLimiter.
  • pip install "python-telegram-bot[webhooks]" installs the tornado~=6.4 _ library. Use this, if you want to use telegram.ext.Updater.start_webhook/telegram.ext.Application.run_webhook.
  • pip install "python-telegram-bot[callback-data]" installs the cachetools>=5.3.3,_ library. Use this, if you want to use arbitrary callback_data _.
  • pip install "python-telegram-bot[job-queue]" installs the `APS

readme truncated — read the full docs on github

Frequently asked questions

Is python-telegram-bot free to use?

python-telegram-bot is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does python-telegram-bot do?

We have made you a wrapper you can't refuse

What is python-telegram-bot written in?

python-telegram-bot is primarily written in Python. Its source is publicly available at https://github.com/python-telegram-bot/python-telegram-bot, and it has 29,468 GitHub stars.