Install & Compatibility
Where this runs
tested against v2.3.3 · 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.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.3s · import 0.770s · 154MB
150MB installed
● package 150MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pytgcalls
✓ from pytgcalls import PyTgCalls
✗ from py_tgcalls import PyTgCalls
Hyphen in package name, but import uses underscore
MediaStream
✓ from pytgcalls.types import MediaStream
✗ from pytgcalls import MediaStream
MediaStream is in pytgcalls.types submodule
GroupCallFactory
✓ from pytgcalls import GroupCallFactory
✗ GroupCallFactory is deprecated in v2; use PyTgCalls directly
GroupCallFactory removed in v2
Basic usage: start a voice chat in a group using Pyrogram and py-tgcalls.
import asyncio
from pyrogram import Client
from pytgcalls import PyTgCalls
from pytgcalls.types import MediaStream
app = Client('my_account', api_id=12345, api_hash='abcdef')
py_tgcalls = PyTgCalls(app)
async def main():
await py_tgcalls.start()
await py_tgcalls.join_group_call(
-1001234567890,
MediaStream(
'https://example.com/audio.ogg',
)
)
await asyncio.Event().wait()
app.run(main())
Errors
Common errors & fixes
pytgcalls.exceptions.AlreadyJoinedError: Already joined to the group call
Calling join_group_call when already in a call without leaving first.
fixCall await py_tgcalls.leave_group_call(chat_id) before joining again.
AttributeError: module 'pytgcalls' has no attribute 'GroupCallFactory'
Using v1 API (GroupCallFactory) with py-tgcalls v2.
fixUpgrade code to use PyTgCalls class. Remove GroupCallFactory and use PyTgCalls(app).
TypeError: Object of type 'MediaStream' is not JSON serializable
Passing MediaStream to something that expects a dict, e.g., as a message reply.
fixDo not serialize MediaStream directly. Use it only with join_group_call or change_stream.
Upgrade
Version history
2.3.3latest on PyPI · released Jun 16, 2026
Audit
Dependencies
pytgcalls[pyrogram]optionalOptional extra for Pyrogram integration
pytgcalls[telethon]optionalOptional extra for Telethon integration