Registry / database / realtime

realtime

JSON →
library2.31.0pypypi✓ verified 27d ago

The `realtime` library is the official Python client for Supabase Realtime, offering capabilities for real-time communication. It allows applications to send and receive ephemeral messages via Broadcast, track and synchronize shared state with Presence, and listen for database changes using Postgres Change Data Capture (CDC). The current version is 2.28.3, and it receives frequent updates as part of the broader Supabase ecosystem.

pip install realtime
INSTALL
IMPORT
SIG · REALTIME
R
realtime
databasepythonv2.31.0
Install
3.6s avg
Import
666ms
Disk
28MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.31.0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.694s · 29.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.6s · import 0.638s · 29MB
28MB installed
● package 28MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AsyncRealtimeClient
from realtime import AsyncRealtimeClient
RealtimeSubscribeStates
from realtime import RealtimeSubscribeStates

This quickstart demonstrates how to establish a connection to the Supabase Realtime server, subscribe to a channel, listen for PostgreSQL database changes, and receive broadcast messages. Remember to replace placeholder `REALTIME_URL` and `SUPABASE_ANON_KEY` with your actual Supabase project details, typically retrieved from your project settings. Ensure your API key has the necessary permissions (e.g., 'anon' key for public read access or a 'service_role' key for elevated privileges).

import asyncio import os from typing import Optional from realtime import AsyncRealtimeClient, RealtimeSubscribeStates async def main(): REALTIME_URL = os.environ.get('REALTIME_URL', 'ws://localhost:4000/websocket') API_KEY = os.environ.get('SUPABASE_ANON_KEY', 'YOUR_SUPABASE_ANON_KEY') # Or your service role key print(f"Connecting to {REALTIME_URL} with API Key: {API_KEY[:5]}...") socket = AsyncRealtimeClient(REALTIME_URL, API_KEY) channel = socket.channel("my_test_channel") def _on_subscribe(status: RealtimeSubscribeStates, err: Optional[Exception]): if status == RealtimeSubscribeStates.SUBSCRIBED: print("Connected to channel!") elif status == RealtimeSubscribeStates.CHANNEL_ERROR: print(f"Error subscribing to channel: {err}") elif status == RealtimeSubscribeStates.TIMED_OUT: print("Subscription timed out.") elif status == RealtimeSubscribeStates.CLOSED: print("Channel unexpectedly closed.") # Listen for database changes (example: all changes in 'public' schema) channel.on_postgres_changes( "*", schema="public", callback=lambda payload: print("Database change received:", payload) ) # Listen for broadcast messages channel.on_broadcast("my-event", lambda payload: print("Broadcast received:", payload)) await channel.subscribe(_on_subscribe) await asyncio.sleep(60) # Keep the client alive for 60 seconds await socket.disconnect() if __name__ == "__main__": # Set these environment variables or replace placeholders for a live connection # os.environ['REALTIME_URL'] = 'wss://<project_ref>.supabase.co/realtime/v1' # os.environ['SUPABASE_ANON_KEY'] = 'eyJ...' asyncio.run(main())
Debug
Known issues
gotchaThe `REALTIME_URL` format is crucial. For local development, it's typically `ws://localhost:4000/websocket`. For a deployed Supabase project, use `wss://<project_ref>.supabase.co/realtime/v1`. Using the incorrect URL can lead to connection failures.
fix
Verify the `REALTIME_URL` against your Supabase project's Realtime connection string in the Supabase Dashboard, or the local Supabase CLI output.
affects: All versions
breakingThe protocol for `postgres_changes` has shifted from using the key 'events' to 'event' in the payload. Older clients expecting 'events' will fail to process real-time database changes correctly.
fix
Update your code to access the change data using `payload['event']` instead of `payload['events']`. This change was noted in `supabase-py`'s v2.27.1 release, which the `realtime` client aligns with.
affects: Pre-2.27.1
gotchaRealtime connections can experience timeouts or failed subscriptions, often due to network instability, incorrect API keys, or server-side issues. Common errors include 'keepalive ping timeout' or 'join push timeout'.
fix
Implement robust error handling and reconnection logic. Ensure your `API_KEY` is valid and has the necessary JWT claims (e.g., `exp` and `role`). Monitor network conditions and Supabase service status. Review GitHub issues for known transient problems.
affects: All versions
deprecatedPython 3.9 support is deprecated and will not be supported in future versions. Python versions below 3.10 will not be supported.
fix
Upgrade your project to Python 3.10 or newer. Regularly check the `realtime` PyPI page or GitHub repository for updated Python version requirements.
affects: All versions
gotchaThe `API_KEY` used for connecting to the Realtime server, especially for private channels, must be a JWT that includes `exp` (expiration) and `role` (database role) claims. An invalid or expired JWT will result in authorization failures.
fix
When generating or using JWTs, ensure they are correctly signed, unexpired, and contain the appropriate `role` claim that matches your Row Level Security (RLS) policies in Supabase.
affects: All versions
Upgrade
Version history
2.31.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
websocketsrequiredRequired for establishing and maintaining WebSocket connections to the Realtime server.
Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources
realtime — pip install realtime · libregistry