{"id":7863,"library":"websockify","title":"websockify","description":"Websockify is a Python library and tool that functions as a WebSocket to TCP proxy/bridge. It translates WebSocket traffic to normal socket traffic, enabling browsers to connect to any application or server. Originally part of the noVNC project, it is actively maintained, with releases typically occurring every few months, incorporating new features and compatibility updates.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/novnc/websockify","tags":["websocket","proxy","tcp","networking","vnc","noVNC"],"install":[{"cmd":"pip install websockify","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Optional dependency for better performance.","package":"numpy","optional":true}],"imports":[{"note":"Primarily used for embedding websockify's core logic within another Python application. Most users interact via the command-line tool.","symbol":"WebSocketProxy","correct":"from websockify.websocketproxy import WebSocketProxy"}],"quickstart":{"code":"# Start websockify to proxy WebSocket connections on port 8080 to a VNC server on localhost:5901\nwebsockify 8080 localhost:5901\n\n# Or, to wrap a program (e.g., a simple telnet server) and proxy to it\n# This example assumes 'nc' (netcat) is available and listening on port 2000\n# In one terminal: nc -lk 2000 # (for Linux)\n# In another terminal, start websockify wrapping nc:\nwebsockify 2023 --wrap-mode=respawn -- nc -lk 2000\n\n# Access via a WebSocket client (e.g., noVNC) pointing to ws://your_server_ip:8080 or ws://your_server_ip:2023","lang":"bash","description":"The primary way to use websockify is as a command-line tool to establish a WebSocket-to-TCP proxy. The first example proxies an existing TCP server (like VNC). The second example demonstrates 'wrap mode', where websockify launches and manages a target program, proxying to its standard I/O or a designated port."},"warnings":[{"fix":"Ensure you are running websockify with Python 3.6 or newer.","message":"Python 2.x and older Python 3 versions are no longer supported. Version 0.13.0 dropped support for Python < 3.6. Earlier versions (0.10.0) required Python 3.4+.","severity":"breaking","affected_versions":">=0.13.0, >=0.10.0"},{"fix":"Update WebSocket clients to use the HyBi/IETF 6455 protocol and send binary data directly (not Base64 encoded). Clients must explicitly support 'binary' protocol.","message":"Older WebSocket protocol versions (Hixie) and Base64 encoding for binary data are no longer supported. Only the HyBi / IETF 6455 WebSocket protocol with binary message frames is supported.","severity":"breaking","affected_versions":">=0.9.0, >=0.5.0"},{"fix":"Refer to the websockify GitHub release notes for v0.6.0 (specifically pull requests #110 and #111) for guidance on updating custom `WebsocketProxy` subclasses.","message":"The internal API for subclassing `WebsocketProxy` was significantly refactored. Custom implementations extending this class will likely break.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"First, navigate to the HTTPS equivalent of your websockify server's address (e.g., `https://your_server_ip:8080`) in your browser and explicitly accept the self-signed certificate. Then, try the `wss://` connection. For production, use a trusted certificate authority.","message":"When using `wss://` (encrypted WebSockets) with self-signed SSL certificates, browsers typically do not prompt to accept the certificate directly from a WebSocket connection. This can lead to connection failures.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Choose a different `source_port` that is not in use, or ensure that any previous websockify instances or other applications are fully terminated before restarting.","cause":"The specified `source_port` for websockify is already in use by another process, or websockify was not properly shut down from a previous run.","error":"OSError: [Errno 10048] Only one usage of each socket address (protocol/network address/port) is normally permitted / Address already in use"},{"fix":"Navigate to the `websockify` source directory and run `make` to compile `rebind.so`. If it's compiled but still not found, check if `rebind.so` is in the expected `websockify/websockify/` directory, and move it there if necessary.","cause":"This error occurs when using `websockify` in `--wrap-mode` on Linux, indicating that the `rebind.so` library (used for intercepting `bind()` system calls) was not found or not built.","error":"Exception: rebind.so not found, perhaps you need to run make"},{"fix":"Ensure the WebSocket client is updated to a modern version that explicitly supports the 'binary' WebSocket sub-protocol as per HyBi/IETF 6455. Avoid older clients that implicitly rely on Base64 encoding.","cause":"An older WebSocket client is attempting to connect to `websockify` using a protocol that requires explicit 'binary' or 'base64' support, or expects Base64 encoding for binary data, which is no longer the default/supported method in recent `websockify` versions.","error":"code 400, message Client must support 'binary' or 'base64' protocol"},{"fix":"Check server logs for specific HTTP status codes (e.g., 400, 401, 403, 404) that might indicate the root cause. Verify the WebSocket URL (ws:// vs wss://), firewall rules, authentication credentials, and ensure correct SSL certificate configuration.","cause":"This generic error can be caused by various issues during the WebSocket handshake, including invalid or missing upgrade headers, authentication/authorization failures, TLS certificate problems (for `wss://`), or network intermediaries (firewalls, proxies) blocking the handshake.","error":"WebSocket connection failed: Error during WebSocket handshake"}]}