csgram

Elegant, modern and asynchronous Telegram MTProto API framework in Python for users and bots

csgram is a drop-in replacement for Pyrogram, with access to the latest Telegram features including Gifts, Stories, Topics, Business Accounts, and more. Import csgram; from pyrogram import ... still resolves to the same module rather than a second copy of it, so an existing Pyrogram codebase runs unchanged.

from csgram import Client, filters

app = Client("my_account")


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


app.run()

csgram is a modern, elegant and asynchronous MTProto API framework. It enables you to easily interact with the main Telegram API through a user account (custom client) or a bot identity (bot API alternative) using Python.

Key Features

• Drop-in Replacement — New code says from csgram import ...; existing from pyrogram import ... codebases migrate with zero changes, since both names are one module.
• Up-to-Date — Supports Gifts, Stories, Topics, Business Accounts, Giveaways, and the latest Telegram layer.
• Async Natively — Fully async/await throughout. Also usable synchronously via app.run() for convenience.
• Type-hinted — Every type and method is annotated for excellent editor support.
• Fast — Boosted by WarpCrypto, a high-performance cryptography library written in Rust.
• Powerful — Full access to Telegram's API for any official client action and more.

Example with Inline Keyboard

from csgram import Client, filters
from csgram.types import InlineKeyboardMarkup, InlineKeyboardButton

app = Client("my_bot")


@app.on_message(filters.command("start"))
async def start(client, message):
    await message.reply(
        "Choose an option:",
        reply_markup=InlineKeyboardMarkup([
            [
                InlineKeyboardButton("Website", url="https://example.com"),
                InlineKeyboardButton("Help", callback_data="help"),
            ],
            [InlineKeyboardButton("About", callback_data="about")],
        ])
    )


app.run()

Installing

pip install csgram

Requires Python 3.10+. On Linux and macOS, csgram[fast] also pulls in uvloop; call uvloop.install() yourself to use it (see the Speedups guide):

pip install csgram[fast]

Development

# Clone the repo
git clone https://github.com/mdsaif572/csgram.git
cd csgram

# Install uv (if not already)
pip install uv

# Create virtual environment with dev dependencies
uv sync --frozen --extra dev

# Generate TL API types
uv run poe api

# Run tests
uv run poe test

Documentation

Full documentation at https://mdsaif572.github.io/csgram

Resources

• Source code
• Documentation
• Issue tracker
• Contributing guide