---
id: centrifuge-python
version: "0.6.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# centrifuge-python — WebSocket SDK for Centrifugo (and any Centrifuge-based server) on top of Python asyncio library

License: permissive · Maintenance: active · Downloads: 195.0K/mo

## What it is and what it does

centrifuge-python is an asyncio-based WebSocket client for connecting to Centrifugo real-time servers. It handles the low-level protocol details of establishing connections, subscribing to channels, publishing messages, and receiving real-time updates from the server. The SDK supports both JSON and Protobuf wire protocols, allowing you to choose between human-readable JSON payloads or more compact binary Protobuf encoding depending on your performance needs.

The library is designed for async Python applications and integrates directly with asyncio event loops. It provides callback-based event handling for connection state changes, subscription updates, and server messages. Configuration options cover TLS customization for secure connections, proxy support (including SOCKS proxies), and protocol selection. The fact sheet notes that callbacks must complete quickly and not raise exceptions, as they run within the SDK's connection read loop.

Use it for:

- Build real-time dashboards or monitoring UIs that receive live updates from a Centrifugo server without polling.
- Implement multi-user collaborative applications where changes made by one user are instantly broadcast to others.
- Create chat or messaging systems with pub/sub channels for group conversations and notifications.
- Connect IoT or backend services to a Centrifugo hub for real-time event distribution across microservices.
- Develop live notification systems that push alerts to connected clients as events occur on the server.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

WebSocket real-time client SDK for Centrifugo and Centrifuge-based servers, built on Python asyncio with support for JSON and Protobuf protocols.

Yes. The package is actively maintained, has low install friction, carries a permissive MIT license, and fills a clear need for asyncio-based real-time communication with Centrifugo servers. No known vulnerabilities. Best suited for projects already using asyncio and needing WebSocket real-time features; ensure your team understands the callback execution model (non-blocking, exception-safe) before integrating.

## Install

pip install centrifuge-python
uv add centrifuge-python
poetry add centrifuge-python

## Installing centrifuge-python

Before you install: Low install friction with only two runtime dependencies (protobuf and websockets). Actively maintained with a release 12 days ago. Supports Python 3.10 through 3.14.

License in practice: MIT license (permissive) means you can use this freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install centrifuge-python

from centrifuge import Client

client = Client("ws://localhost:8000/connection/websocket")

Requires Python 3.10 or later. SOCKS proxy support requires optional python-socks package.

Verify before relying:

- Whether the SDK implements all features from the Centrifugo client SDK feature matrix mentioned in the description.
- Performance characteristics under high message throughput or concurrent subscriptions.
- Reconnection behavior and backoff strategy details beyond what the description states.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 195.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

websocket real-time client, centrifugo python sdk, asyncio websocket messaging, pub/sub real-time communication, centrifuge-based server client, asyncio, websocket, real-time

[View on SkillFed](https://skillfed.io/packages/centrifuge-python) · [View on PyPI](https://pypi.org/project/centrifuge-python/)