Skip to main content

WebSocket client for Python with low level API options

Project description

docs Build Status codecov PyPI Downloads PyPI version


websocket-client is a WebSocket client for Python. It provides access to low level APIs for WebSockets. websocket-client implements version hybi-13 of the WebSocket procotol. This client does not currently support the permessage-deflate extension from RFC 7692.


This project's documentation can be found at


Please see the contribution guidelines


First, install the following dependencies:

  • six
  • backports.ssl_match_hostname for Python 2.x

You can install the dependencies with the command pip install six and pip install backports.ssl_match_hostname

You can use either python install or pip install websocket-client to install. This module is tested on Python 2.7 and Python 3.4+. Python 3 support was first introduced in version 0.14.0, but is a work in progress.

Usage Tips

Check out the documentation's FAQ for additional guidelines:

Known issues with this library include lack of WebSocket Compression support (RFC 7692) and minimal threading documentation/support.


  • LGPL version 2.1


The send and validate_utf8 methods are very slow in pure Python. You can disable UTF8 validation in this library (and receive a performance enhancement) with the skip_utf8_validation parameter. If you want to get better performance, please install both numpy and wsaccel, and import them into your project files - these other libraries will automatically be used when available. Note that wsaccel can sometimes cause other issues.

Long-lived Connection

Most real-world WebSockets situations involve longer-lived connections. The WebSocketApp run_forever loop automatically tries to reconnect when a connection is lost, and provides a variety of event-based connection controls. The project documentation has additional examples

import websocket
    import thread
except ImportError:
    import _thread as thread
import time

def on_message(ws, message):

def on_error(ws, error):

def on_close(ws):
    print("### closed ###")

def on_open(ws):
    def run(*args):
        for i in range(3):
            ws.send("Hello %d" % i)
        print("thread terminating...")
    thread.start_new_thread(run, ())

if __name__ == "__main__":
    ws = websocket.WebSocketApp("ws://",
                              on_open = on_open,
                              on_message = on_message,
                              on_error = on_error,
                              on_close = on_close)


Short-lived Connection

This is if you want to communicate a short message and disconnect immediately when done. For example, if you want to confirm that a WebSocket server is running and responds properly to a specific request. The project documentation has additional examples

from websocket import create_connection
ws = create_connection("ws://")
print("Sending 'Hello, World'...")
ws.send("Hello, World")
result =  ws.recv()
print("Received '%s'" % result)

If you want to customize socket options, set sockopt, as seen below:

from websocket import create_connection
ws = create_connection("ws://",
                        sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY),))


Thanks to @battlemidget and @ralphbean for helping migrate this project to Python 3.

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

websocket-client-0.59.0.tar.gz (57.9 kB view hashes)

Uploaded source

Built Distribution

websocket_client-0.59.0-py2.py3-none-any.whl (67.2 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page