Python Framework for the Telegram MTProto API
Homepage • Documentation • Releases • News

Hydrogram is an asynchronous Python library for the Telegram MTProto API. Build bots and user clients with high-level methods, message handlers, and filters, or access the raw API when you need more control.

Requires Python 3.11 or later. Install or upgrade with pip:

python -m pip install --upgrade hydrogram

To include optional performance dependencies (TgCrypto and, on supported platforms, uvloop):

python -m pip install --upgrade "hydrogram[fast]"

See the speedups guide for details, including how to enable uvloop.

Get your api_id and api_hash from my.telegram.org/apps. Replace the placeholders below with your credentials and save the example as hello.py. It replies to private messages from other users:

from hydrogram import Client, filters

app = Client(
    "my_account",
    api_id=12345,
    api_hash="0123456789abcdef0123456789abcdef",
)


@app.on_message(filters.private & ~filters.me)
async def hello(client, message):
    await message.reply("Hello from Hydrogram!")


app.run()

Run python hello.py and follow the sign-in prompts. Once connected, send a private message to the account from another account to see the reply. Hydrogram saves the login in my_account.session for subsequent runs; keep this file private.

To sign in as a bot, also pass bot_token to Client. See authorization and the examples for more.

• Async API: Use async and await to handle updates and make concurrent requests.
• High-level interface: Work with messages, chats, and users through convenient methods and bound objects.
• Handlers and filters: Route updates to callbacks with composable filters.
• Raw API access: Call MTProto methods from the API layer supported by Hydrogram.
• Type hints: Get editor completion and support for static analysis.
• Optional speedups: Use TgCrypto for faster cryptography and uvloop as an alternative event loop.

• The documentation is the technical reference for Hydrogram. It includes detailed usage guides, API reference, and more.
• The homepage is the official website for Hydrogram. It includes a quickstart guide, a list of features, and more.
• Our Telegram channel is where we post news and updates about Hydrogram.
• Ask questions in GitHub Discussions, or report bugs through GitHub Issues.

Hydrogram is an open source project and we welcome contributions from the community. We appreciate all types of contributions, including bug reports, feature requests, documentation improvements, and code contributions.

See the Contributing Guide for development setup, tests, and pull request guidelines.

All contributors are expected to adhere to the Code of Conduct. Please read it before contributing.

Hydrogram is an open source project. Your support helps us maintain and improve the library. You can support the development of Hydrogram through the following platforms:

• Liberapay
• OpenCollective

• Pyrogram and its contributors for the inspiration and base code.

Hydrogram is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). See COPYING.lesser and COPYING for the full license terms, and NOTICE for copyright information.