Install & Compatibility
Where this runs
tested against v0.10.1 · 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
✕ build_error
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WebSocketServer
✓ from geventwebsocket import WebSocketServer
WebSocketApplication
✓ from geventwebsocket import WebSocketApplication
Resource
✓ from geventwebsocket import Resource
WebSocketHandler
✓ from geventwebsocket.handler import WebSocketHandler
WebSocketError
✓ from geventwebsocket import WebSocketError
Used for catching WebSocket-specific exceptions.
This quickstart sets up a basic WebSocket echo server using the `WebSocketApplication` and `WebSocketServer` classes. It listens on `ws://localhost:8000/` and echoes any received message back to the client. This is the higher-level API for defining WebSocket applications.
from gevent import pywsgi
from geventwebsocket import WebSocketServer, WebSocketApplication, Resource
from collections import OrderedDict
class EchoApplication(WebSocketApplication):
def on_open(self):
print("Connection opened")
def on_message(self, message):
# Echo the received message back to the client
print(f"Received: {message}")
self.ws.send(message)
def on_close(self, reason):
print(f"Connection closed: {reason}")
if __name__ == '__main__':
print("Starting WebSocket echo server on ws://localhost:8000/")
server = WebSocketServer(
('', 8000),
Resource(OrderedDict([('/', EchoApplication)]))
)
try:
server.serve_forever()
except KeyboardInterrupt:
print("Server stopped.")
Debug
Known issues
deprecatedThe library's last release was in March 2017, indicating a low maintenance or potentially abandoned status. Users seeking actively developed WebSocket solutions with gevent might consider alternatives like `gevent-ws` which explicitly states itself as an MIT-licensed alternative to the 'abandoned' gevent-websocket.fixEvaluate newer alternatives for active development and support, or be aware of the limited maintenance for this library.
affects: <=0.10.1
breakingThe `wait()` method was renamed to `receive()` in earlier versions (pre-0.10.1). If upgrading from very old versions or referencing outdated documentation, this change can cause `AttributeError`s.fixAlways use `ws.receive()` to get messages from the WebSocket connection.
affects: <0.10.1
gotchaWhen integrating with WSGI applications (especially with `WebSocketHandler`), the WebSocket object is exposed via `environ['wsgi.websocket']`. Applications must explicitly check for the presence of this key to determine if a request is a WebSocket upgrade or a standard HTTP request.fixAlways check `if 'wsgi.websocket' in environ:` before attempting to access the WebSocket object and handle standard HTTP requests accordingly.
affects: All versions
gotchaWhen combining `gevent-websocket` with `Flask-SocketIO`, installing `gevent-websocket` can unexpectedly break `Flask-SocketIO`'s WebSocket server functionality, leading to connections immediately closing, even though `Flask-SocketIO` itself might recommend installing it for performance.fixCarefully test integration with other WebSocket-dependent libraries. If issues arise, consider removing `gevent-websocket` if `Flask-SocketIO` handles its own WebSocket transport effectively, or explore the specific `Flask-SocketIO` worker classes that might conflict.
affects: 0.10.1 (and potentially others when combined with specific `Flask-SocketIO` and `gevent` versions)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'geventwebsocket'
The Python package is named `gevent-websocket` (with a hyphen) and should be installed using `pip install gevent-websocket`. However, developers often incorrectly attempt to import it directly as `geventwebsocket` (without a hyphen) or the package is simply not installed in the environment.
fixFirst, ensure the library is installed: `pip install gevent-websocket`. Then, use the correct import path, typically from the `geventwebsocket` sub-package or modules within it, for example: `from geventwebsocket import WebSocketServer`.
RuntimeError: You need to use the gevent-websocket server.
This error arises when an application (often using frameworks like Flask-SocketIO) is configured to use `gevent` for WebSocket handling, but the underlying WSGI server employed is not the `gevent-websocket` compatible server or is not correctly set up to integrate with it.
fixEnsure you are running your application with a server that correctly uses `gevent-websocket`. For Flask-SocketIO, this often means removing explicit `async_mode='threading'` if present and ensuring both `gevent` and `gevent-websocket` are installed. If using Gunicorn, specify the `geventwebsocket` worker class: `gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker app:app`.
command 'gcc' failed with exit status 1
This common compilation error during `pip install gevent-websocket` (or its dependency `gevent`) indicates that essential C development headers, specifically for the `libevent` library, are missing from the system. `gevent` relies on `libevent` for its asynchronous I/O capabilities.
fixInstall the `libevent` development package appropriate for your operating system. For Debian/Ubuntu-based systems: `sudo apt-get install libevent-dev`. For Red Hat/CentOS-based systems: `sudo yum install libevent-devel`.
ModuleNotFoundError: No module named 'gevent.wsgi'
This error occurs because the `gevent.wsgi` module was deprecated and removed in `gevent` version 1.3. The correct module to import for WSGI server functionality in newer `gevent` versions is `gevent.pywsgi`.
fixUpdate your import statement from `from gevent.wsgi import WSGIServer` to `from gevent.pywsgi import WSGIServer`.
Upgrade
Version history
0.10.1latest on PyPI · released Mar 12, 2017
Audit
Dependencies
geventrequiredCore dependency for asynchronous I/O and WSGI server integration.
wsacceloptionalOptional dependency for performance acceleration, especially for UTF8 validation and frame masking/demasking.
ujsonoptionalOptional dependency for performance acceleration of JSON operations.
simplejsonoptionalOptional dependency for performance acceleration of JSON operations (alternative to ujson).
gunicornoptionalOptional dependency for deploying gevent-websocket applications with Gunicorn using a specific worker class.