Kurigram: a maintained Pyrogram fork that keeps the pyrogram import name

The import statement does not change

Kurigram is a fork of Pyrogram, and the single most consequential decision in it is that the package still imports as pyrogram. The example in the README is the familiar Pyrogram shape:

from pyrogram import Client, filters

app = Client("my_account")


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


app.run()

The README calls it a drop-in replacement, and that claim is what makes the fork worth a look. Migrating means changing the dependency, not changing the code, and the decorator-based handler style, the Client constructor, the filters module and the run call all stay as they were. For a codebase with hundreds of call sites that is the difference between an afternoon and a project.

The fork exists because Telegram moved. The description lists the features it adds support for: Gifts, Stories, Topics, Business Accounts and more, described as the latest Telegram features. Upstream Pyrogram has a slow release rhythm in comparison, and the fork exists to carry the MTProto layer forward while keeping the API shape that existing applications depend on.

What the fork does not claim is a reimplementation. It presents itself as the same framework with newer Telegram coverage, and the maintenance model is what the project sells.

MTProto against a user account, not just the Bot API

Kurigram is a Telegram MTProto API framework, and the documentation distinguishes that from the Bot API. The point it makes is that you can interact with the main Telegram API through a user account, described as a custom client, or through a bot identity as an alternative to the Bot API.

That distinction is the practical one. The Bot API is a narrow slice of what Telegram can do, and everything Telegram ships for consumers that is not exposed through it, including business accounts and gifts, requires the MTProto layer. A framework that speaks MTProto as a user account can do things a bot token cannot, including reading the chats the account is in and acting as the account rather than as a bot.

The cost of that reach is visible in the dependencies and in the design. The library is fully asynchronous, and it is usable synchronously as well if you want convenience. The low-level details of the protocol are abstracted and re-presented in a more convenient way, which is the stated reason the API is described as elegant.

The feature list also covers the practical expectations of a working client. It is type-hinted throughout, with types and methods annotated so editors can help you, which matters more in a project this size than in a small script. It is fast, boosted by TgCrypto, a cryptography library written in C, and it offers full access to Telegram's API to execute any official client action.

Installation, extras and the version range

The stable release installs like any other package:

pip install kurigram

The development version comes straight from the repository:

pip install https://github.com/kurigram-org/kurigram/archive/main.zip --force-reinstall

And two optional extras are documented. The fast extra pulls TgCrypto and uvloop:

pip install kurigram[fast]     # TgCrypto and uvloop for better performance
pip install kurigram[qrcode]   # QR code login support

The qrcode extra is worth understanding, because it points at a specific part of MTProto. Logging in as a user account rather than a bot is an interactive process, and a QR code is one of the ways that interaction can happen without typing a code into the console.

The supported Python range is wide and unusual for a library of this kind. requires-python is >=3.10, and the classifiers cover Python 3.10 through 3.15, on both CPython and PyPy. The Makefile reflects that range being tested at both ends rather than assumed, with a floor environment and a ceiling environment, and the comment in the Makefile says the two ends of the supported range should be kept in sync with the project file.

The build system is hatchling, and the project file notes that the PEP 639 licence metadata needs a recent hatchling, since below that version the build fails with an error about the licence-files field. The project version is dynamic rather than written in the file, with the Makefile reading it back through hatchling.

A Makefile that owns the environment

The Makefile is the part of this repository that tells you how the project is actually worked on. The approach it takes is to let uv own the environment entirely. The comment is explicit that uv run creates the virtual environment and installs from the lock file whenever it is missing or out of date, so no recipe below has to build one first and there is no step a contributor can forget.

That is a small design decision with real consequences. A contributor who runs a single documented target does not have to know whether the environment exists or whether the lock file is current, because the tool answers that at invocation time rather than through a bootstrap step that can be forgotten.

The available targets, taken from the .PHONY list, cover the usual lifecycle plus a few that reveal the project's structure. There is sync, clean variants for the environment, the build and the api, and separate targets for building the api and the docs. There is a version target and tag and dtag targets for releases. Lint, format and typecheck are separate targets. The test target list is more interesting than usual: test-unit, test-guards and test-integration, plus test-floor and test-ceil, which run against the oldest and newest supported interpreters.

The live tests take every parameter from the environment. A git-ignored .env.test file carries them locally and the runner loads it, so nothing under the tests directory has to read a file of its own, and absent the file the tests skip by name rather than fail. The repository also ships an .env.test.example, so the shape of the file is documented without committing the values.

Licensing, packaging and the compilation step

The licence is LGPL-3.0, and the classifier records it as the GNU Lesser General Public License v3. The repository root carries both a COPYING file and a COPYING.lesser file, which is the conventional pair for LGPL projects, along with a NOTICE file.

The LGPL matters here in a way it does not for most libraries, because Kurigram is a fork of Pyrogram and Pyrogram is itself LGPL. A project that wants to redistribute a modified Kurigram, or to link it into a larger application, is in the territory the LGPL was written for, and the two licence files are the place to read about it. That is worth doing before shipping, because the obligations around modified versions of an LGPL library differ from those around unmodified use.

The packaging setup is also unusual for a Python library. There is a compiler directory at the top level, a hatch_build.py, and the Makefile comment explains that the api target runs its compilers from inside that directory. The project also keeps a uv.lock, a pre-commit configuration, a contributing guide and a tests directory.

The result is a package that ships generated API code rather than hand-written bindings for every Telegram layer. For a framework that has to track a protocol with hundreds of methods, generating that surface is the difference between a library that can keep up with Telegram and one that cannot.

Where Kurigram is the wrong choice

The first consideration is that a fork of a fork is a dependency with an extra question mark on it. Pyrogram itself was a fork in the sense that it rebuilt the Telegram library for modern asyncio Python, and Kurigram forks that. Each layer adds a maintenance boundary and a place for a behaviour to differ from what you expect. If your application does not need the newer Telegram features, the honest comparison is with upstream Pyrogram, which is one link closer to whatever Pyrogram's own maintainers decide.

The second is the MTProto surface itself. Using a user account rather than a bot means you are responsible for the account: its session file, its phone number, and the risk that an account used for automation is restricted. A bot token has none of those properties, and if your use case is a Telegram bot reacting to messages, the Bot API is the simpler and safer route. The framework supports the bot identity path, but the features the fork highlights are on the user side.

The third is that the library moves fast, and fast in a protocol client means the API can change between versions. The release history shows v2.2.24, v2.2.25 and v2.2.26 in the space of a couple of months, and the development install pulls straight from the main branch. That is a good thing for keeping up with Telegram and a nuisance for pinning a reproducible production environment, so pin the version and read the changelog rather than tracking main.

What the project is genuinely good for is the case it was made for: a Python application that needs to read or send as a user account and that needs Telegram features the mainstream client libraries lag on. For that case, the drop-in property and the current feature coverage are worth the extra dependency layer.

Editorial conclusion

Kurigram fits a Python developer who needs recent Telegram features that upstream Pyrogram does not yet expose, and who wants to change one dependency line rather than rewrite a codebase. It does not fit a team that wants upstream Pyrogram's own roadmap or that has a policy against depending on a fork of a fork. Before adopting it, confirm your Telegram layer uses the MTProto API rather than the Bot API, since the fork's value is in the user-account side, decide whether you need the fast extra for TgCrypto and uvloop, and read the licensing position yourself, since the library is LGPL and the repository ships both a COPYING file and a COPYING.lesser file.

Frequently asked questions

Official sources

1. kurigram-org/kurigram on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases