Install & Compatibility
Where this runs
tested against v4.32.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
py 3.9
✕ build_error
✓ 6.9s
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StreamChat
✓ from stream_chat import StreamChat
Initializes the Stream Chat client, upserts a user, generates a user token for client-side authentication, creates or retrieves a channel, and sends a message to it. Ensure `STREAM_API_KEY`, `STREAM_API_SECRET`, and `STREAM_USER_ID` are set as environment variables or replaced with actual values.
import os
from stream_chat import StreamChat
# Initialize the client with your API Key and Secret
# Get these from your Stream Dashboard: https://getstream.io/dashboard/
STREAM_API_KEY = os.environ.get('STREAM_API_KEY', 'YOUR_STREAM_API_KEY')
STREAM_API_SECRET = os.environ.get('STREAM_API_SECRET', 'YOUR_STREAM_API_SECRET')
STREAM_USER_ID = os.environ.get('STREAM_USER_ID', 'test_user_id')
if not all([STREAM_API_KEY, STREAM_API_SECRET]):
raise ValueError("STREAM_API_KEY and STREAM_API_SECRET environment variables must be set.")
client = StreamChat(api_key=STREAM_API_KEY, api_secret=STREAM_API_SECRET)
# Create/update a user
user_data = {"id": STREAM_USER_ID, "name": "Test User"}
client.upsert_user(user_data)
print(f"User '{STREAM_USER_ID}' upserted.")
# Create a user token for client-side authentication (e.g., in a frontend app)
token = client.create_token(STREAM_USER_ID)
print(f"Generated user token: {token}")
# Create a channel
channel_id = "general"
channel_type = "messaging"
channel = client.channel(channel_type, channel_id)
channel.create(STREAM_USER_ID)
print(f"Channel '{channel_type}:{channel_id}' created/initialized.")
# Send a message to the channel
message_data = {"text": "Hello from the Python client!"}
channel.send_message(message_data, STREAM_USER_ID)
print("Message sent!")
Debug
Known issues
breakingThe `stream-chat` library is in maintenance mode. While it continues to receive critical updates, new projects are strongly advised to use the newer `getstream` Python SDK (`pip install getstream`). The `getstream` library is the actively developed, full-product SDK covering Chat, Video, Moderation, and Feeds.fixFor new projects, install and use `getstream` instead: `pip install getstream`. Refer to the official Stream documentation for migration guides if moving an existing project.
affects: All versions >=4.x.x
gotchaAs of v4.0, API responses are instances of `StreamResponse`, which inherits from `dict`. While backward compatible (you can access data like a dictionary), it also provides additional methods like `.rate_limit()`, `.headers()`, and `.status_code()` for enhanced metadata access. Unexpected type checks might fail if only `dict` is assumed.fixAccess response data as you would with a dictionary, but be aware of the `StreamResponse` type for additional methods. Example: `resp = client.call_api(...); print(resp.rate_limit()); data = resp['some_key']`.
affects: >=4.0.0
gotchaDo not rely on parsing error messages for business logic. Error messages are subject to change and may vary. Always use HTTP status codes and Stream's internal error codes for robust error handling.fixImplement error handling based on `resp.status_code()` and the error codes provided in the response body, rather than string matching against error messages.
affects: All versions
Errors
Common errors & fixes
StreamChatAPIException: Authentication Error: Invalid credentials provided for StreamChat.
The API Key or API Secret provided during `StreamChat` client initialization is incorrect or missing.
fixDouble-check your `STREAM_API_KEY` and `STREAM_API_SECRET` in your environment variables or code. Ensure they match the credentials found in your Stream Dashboard (https://getstream.io/dashboard/). Verify there are no leading/trailing spaces or typos.
StreamChatAPIException: GetOrCreateChannel failed with error: "either data.created_by or data.created_by_id must be provided when using server side auth."
When creating a channel using server-side authentication (i.e., with an API Secret), the `created_by` or `created_by_id` field is missing in the channel creation data.
fixEnsure that the `create()` method for a channel is called with a `created_by_id` parameter, which specifies the user creating the channel. Example: `channel.create(created_by_id='your-user-id')`.
StreamChatAPIException: Channel with given ID does not exist
An operation was attempted on a channel (e.g., `channel.watch()`, `channel.send_message()`) that has not yet been created or initialized on the Stream platform.
fixBefore performing operations on a channel, ensure it has been properly created or retrieved. Call `channel.create(created_by_id='...')` to create the channel, or use `client.query_channels(...)` to retrieve existing ones.
Upgrade
Version history
4.32.0latest on PyPI · released May 15, 2026
Audit
Dependencies
No dependency data recorded yet.