Install & Compatibility
Where this runs
tested against v1.1.16 · 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
installs and imports cleanly · install 0.0s · import 1.470s · 94MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 0.566s · 117MB
108MB installed
● package 108MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Room
✓ from livekit import rtc
AccessToken
✓ from livekit import access_token as at
VideoGrants
✓ from livekit import access_token as at
This quickstart demonstrates how to connect to a LiveKit room, generate an access token, listen for basic room events (participant connected/disconnected, room disconnected), and properly disconnect. Ensure you have `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` environment variables set to connect to your LiveKit server.
import asyncio
import os
from livekit import rtc, access_token as at
async def main():
# Environment variables for LiveKit server URL and API credentials
livekit_url = os.environ.get('LIVEKIT_URL', 'ws://localhost:7880')
api_key = os.environ.get('LIVEKIT_API_KEY', 'devkey')
api_secret = os.environ.get('LIVEKIT_API_SECRET', 'secret')
# Participant identity and room name
identity = "my-python-participant"
room_name = "my-test-room"
# Create an access token with necessary grants
grants = at.VideoGrants(room_join=True, room=room_name)
token = at.AccessToken(api_key, api_secret).with_identity(identity).with_grants(grants).to_jwt()
# Initialize a Room
room = rtc.Room()
# Define event handlers
@room.on("participant_connected")
def on_participant_connected(participant: rtc.RemoteParticipant):
print(f"Participant connected: {participant.identity} (sid: {participant.sid})")
@room.on("participant_disconnected")
def on_participant_disconnected(participant: rtc.RemoteParticipant):
print(f"Participant disconnected: {participant.identity}")
@room.on("room_disconnected")
def on_room_disconnected():
print("Room disconnected")
try:
print(f"Connecting to LiveKit room: {room_name} at {livekit_url}")
await room.connect(livekit_url, token, rtc.RoomOptions())
print(f"Connected to room {room.name} as {room.local_participant.identity}")
# Keep the room alive for a short period or until manually disconnected
print("Staying in room for 10 seconds...")
await asyncio.sleep(10)
except Exception as e:
print(f"Error connecting to room: {e}")
finally:
print("Disconnecting from room...")
await room.disconnect()
print("Disconnected.")
if __name__ == "__main__":
# LiveKit requires Python 3.9+
if os.environ.get('LIVEKIT_URL') and os.environ.get('LIVEKIT_API_KEY') and os.environ.get('LIVEKIT_API_SECRET'):
asyncio.run(main())
else:
print("Please set LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET environment variables.")
Debug
Known issues
gotchaThe LiveKit Python SDK is built asynchronously using `asyncio`. Forgetting to `await` async functions or not running the main application within an `asyncio` event loop is a common mistake that will prevent the SDK from functioning correctly.fixAlways use `await` when calling `async` methods (e.g., `await room.connect()`, `await room.disconnect()`). Run your main application logic within `asyncio.run(main_async_function())`.
affects: All versions
gotchaIncorrectly generating `AccessToken` with invalid `identity`, `name`, `grants`, or an expired time can lead to connection failures or unauthorized access to LiveKit rooms. Ensure participant identity is unique and grants match required permissions.fixDouble-check the `api_key`, `api_secret`, `identity`, and `VideoGrants` (e.g., `room_join=True`, `room=room_name`) when creating tokens. LiveKit's server logs can provide insights into token validation failures.
affects: All versions
breakingVersions 1.1.1 and 1.1.2 introduced changes to how `memoryview` and `bytes` are handled in `AudioFrame` and `VideoFrame` (e.g., `materialize sliced memoryviews`, `normalize memoryview format`). This primarily affects applications directly manipulating raw audio/video data.fixReview custom frame processing logic to ensure compatibility with `bytes` data types and proper memory handling. Explicitly convert `memoryview` to `bytes` if necessary to avoid unexpected data format issues.
affects: 1.1.1, 1.1.2, and later
gotchaFailing to explicitly call `await room.disconnect()` will leave the client connected to the LiveKit server, consuming resources and potentially delaying cleanup or leading to unexpected behavior on subsequent connection attempts.fixAlways ensure `await room.disconnect()` is called, ideally within a `finally` block or an appropriate cleanup routine, to gracefully terminate the connection.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyaudioop'
This error typically occurs when a `livekit` plugin, such as `livekit-plugins-clova`, depends on a module (`audioop` or its fallback `pyaudioop`) that has been removed from newer Python versions (e.g., Python 3.13) or is a missing dependency.
fixInstall the recommended replacement or the specific missing plugin. For `pyaudioop` on Python 3.13+, install `audioop-lts`. For other `ModuleNotFoundError`s related to `livekit` plugins, ensure all required plugins are installed (e.g., `pip install livekit-plugins-openai livekit-plugins-deepgram`).
ModuleNotFoundError: No module named 'lk_blingfire'
This error indicates that the `livekit-blingfire` package, or its underlying C extension `lk_blingfire`, is not correctly installed or compatible with your Python environment, often appearing after updates or with specific Python versions like 3.14.
fixEnsure `livekit-blingfire` is installed and, if encountering issues, try installing a specific compatible version (e.g., `pip install livekit-blingfire==1.0.0` if `1.0.1` was yanked) or check for updates that explicitly support your Python version.
AttributeError: 'Room' object has no attribute 'participants'
This error occurs when trying to access `participants` directly on a `Room` object before the room has fully connected or before the participant list is populated, or due to changes in the SDK's API where `participants` might be accessed differently or only after certain events.
fixEnsure the `Room` object has successfully connected and that you are accessing `participants` (or `remote_participants`) in the correct context, often after a `connected` event or in an asynchronous flow where the room state is managed. You might need to iterate over `room.remote_participants.values()` for remote participants.
AttributeError: 'Room' object has no attribute 'local_participant'
This `AttributeError` indicates that `local_participant` is being accessed on the `Room` object before the participant has been initialized or connected to the room, or that the API usage has changed and an explicit `connect()` call or similar setup is now required.
fixEnsure that the `Room` object has been explicitly connected using `await room.connect(...)` and that the `local_participant` is available only after a successful connection. Check the latest `livekit` SDK examples for the correct connection and participant access pattern.
AttributeError: Assignment not allowed to message field "numbers" in protocol message object
This error typically arises when attempting to directly assign a `ListUpdate` or similar message-typed object to a repeated field within a Protobuf message (like `SIPInboundTrunkUpdate`) in Python, which is not allowed by the Protobuf API. Instead, fields must be set using methods like `CopyFrom()` or by mutating the existing message.
fixWhen working with Protobuf messages and repeated fields, avoid direct assignment. Instead, use the appropriate Protobuf methods to update the field, such as `message.field.CopyFrom(new_value)` or by extending the list directly if it's a primitive type. For `livekit.api` objects, ensure you are using helper methods if available, or construct the update object correctly.
Upgrade
Version history
1.1.16latest on PyPI · released Aug 24, 2026
Audit
Dependencies
No dependency data recorded yet.