Install & Compatibility
Where this runs
tested against v2.0.106 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.725s · 43.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.1s · import 1.522s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from pyrogram import Client
filters
✓ from pyrogram import filters
RPCError
✓ from pyrogram import errors; errors.RPCError
✗ from pyrogram import Error
The `errors` package was moved and `Error` renamed to `RPCError` in v0.12.0.
idle
✓ from pyrogram import idle
✗ Client.idle()
The `idle()` method was reworked to be a static function, not a client method, and no longer stops the client automatically.
This quickstart initializes a Pyrogram client (which can act as a user account or bot). It requires `api_id` and `api_hash` from my.telegram.org/apps set as environment variables `TG_API_ID` and `TG_API_HASH`. For bots, `TG_BOT_TOKEN` should also be set. The client will create a `.session` file for persistent login. It includes a simple `start` command handler.
import os
from pyrogram import Client, filters
import asyncio
API_ID = os.environ.get('TG_API_ID', '')
API_HASH = os.environ.get('TG_API_HASH', '')
BOT_TOKEN = os.environ.get('TG_BOT_TOKEN', '') # Optional, for bot accounts
async def main():
if not API_ID or not API_HASH:
print("Please set TG_API_ID and TG_API_HASH environment variables.")
return
# For a user account, use Client("my_account", api_id, api_hash)
# For a bot account, use Client("my_bot", api_id, api_hash, bot_token)
async with Client(
"my_session", # Session name, creates my_session.session file
api_id=int(API_ID),
api_hash=API_HASH,
bot_token=BOT_TOKEN if BOT_TOKEN else None # Pass bot_token only for bots
) as app:
me = await app.get_me()
print(f"Client started as {me.first_name} (@{me.username})")
@app.on_message(filters.command("start") & filters.private)
async def start_command(client, message):
await message.reply_text("Hello! I'm a Pyrogram client/bot.")
# Keep the client running indefinitely. In a real app, you might use app.run()
# or integrate with other async loops.
print("Listening for messages...")
await asyncio.Event().wait() # Keeps the client running indefinitely
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingProject is no longer maintained or supported. Users should be aware that new features, bug fixes, or security updates are unlikely.fixConsider migrating to actively maintained alternatives or be prepared to fork and maintain the library yourself. Proceed with caution for new projects.
affects: All versions from 2.0.106 onwards (as of December 2024)
breakingAuthorization flow changed: Callback functions for `Client` arguments (e.g., `phone_number`, `password`) were removed in favor of a simpler, sequential authorization.fixUpdate authorization logic to use the direct parameters or environmental variables for `api_id`, `api_hash`, `phone_number`, `password`, etc., and follow the interactive login flow if necessary.
affects: Versions after Pyrogram v0.16.0
breakingThe `idle()` method no longer automatically stops the client. It only idles.fixExplicitly call `app.stop()` after `idle()` finishes if you want to terminate the client gracefully.
affects: Versions after Pyrogram v0.16.0
gotchaSession persistence is managed via session files (SQLite by default). For ephemeral environments or explicit in-memory use, `in_memory=True` must be passed to `Client`.fixUnderstand the `name` and `in_memory` parameters of `Client` to control session storage. Use `export_session_string()` for portable in-memory sessions across restarts.
affects: All versions
gotchaAll Pyrogram operations are asynchronous. Blocking operations (e.g., `time.sleep()`, synchronous network requests) in handlers will freeze the event loop and prevent other updates from being processed.fixAlways use `await` with Pyrogram methods and other asynchronous libraries (e.g., `asyncio.sleep()`, `aiohttp`). Ensure your code is fully asynchronous.
affects: All versions
Upgrade
Version history
2.0.106latest on PyPI · released Apr 30, 2023
Audit
Dependencies
pyaes | pysocksrequiredRequired for cryptographic operations or proxy support.
tgcryptooptionalOptional C-based cryptography library for significantly better performance.
Resources
No resource links recorded.