WebSockets enable real-time, bidirectional communication between a client and a server. Unlike traditional HTTP requests, which are request-response based, WebSockets maintain a persistent connection allowing data to flow continuously in both directions. Let us delve into understanding how to use WebSockets from Python to FastAPI.<\/p>\n
A WebSocket<\/a> is a communication protocol that enables full-duplex (two-way) communication over a single, long-lived TCP connection. Unlike traditional HTTP, which follows a request-response model, WebSockets allow both the client and server to send data at any time without repeatedly opening new connections. This makes them ideal for real-time applications such as chat apps, live notifications, multiplayer games, and streaming dashboards.<\/p>\n WebSocket disconnections can occur due to several reasons:<\/p>\n In production systems, it is important to handle disconnections gracefully to avoid memory leaks, dangling connections, or inconsistent application state. You may also implement reconnection logic on the client side.<\/p>\n You can also perform cleanup tasks inside the exception block, such as removing the client from an active connections list.<\/p>\n This example brings everything together into one cohesive setup, including a FastAPI WebSocket server, a Python client, seamless file transfer over WebSockets, and proxying communication to an external WebSocket service. Before running the example, ensure you have the required dependencies installed. This setup uses FastAPI for building the WebSocket server, Uvicorn as the ASGI server, and the Make sure you are using Python 3.8 or above for proper async support. Also, ensure that the required ports (default: 8000) are available and not blocked by firewall rules.<\/p>\n This code defines a WebSocket endpoint in FastAPI that handles multiple communication flows within a single persistent connection. The application initializes a FastAPI server and exposes a The above command starts the FastAPI application using Uvicorn, an ASGI server designed for asynchronous frameworks. The This code implements an asynchronous Python WebSocket client using the After running both the FastAPI WebSocket server and the Python client, the following outputs can be observed. These outputs demonstrate how different communication flows (text, file transfer, and proxying) are handled over a single persistent WebSocket connection.<\/p>\n The server logs show the lifecycle of the connection. Initially, the client establishes a connection, followed by a text message being received and processed. The server then switches to file transfer mode, where it starts receiving binary chunks and writes them to a file. Once all operations are complete and the client closes the connection, the server detects the disconnection and logs it accordingly.<\/p>\n The client output confirms successful round-trip communication for each flow. The text message is echoed back by the server, the file transfer is acknowledged after complete upload, and the proxy flow demonstrates that the server successfully forwarded the request to an external WebSocket service and returned its response.<\/p>\n1.1 Key Features<\/h3>\n
\n
1.2 WebSocket Connection Lifecycle<\/h3>\n
\n
Upgrade<\/code> header. If the server supports WebSockets, it upgrades the connection to a WebSocket protocol.<\/li>\n1.3 Common Methods<\/h3>\n
\n
connect()<\/code> \u2013 Establishes the WebSocket connection.<\/li>\naccept()<\/code> \u2013 (FastAPI-specific) Accepts an incoming WebSocket request.<\/li>\nsend_text()<\/code> \/ send_bytes()<\/code> \u2013 Sends data to the client.<\/li>\nreceive_text()<\/code> \/ receive_bytes()<\/code> \u2013 Receives data from the client.<\/li>\nclose()<\/code> \u2013 Closes the connection gracefully.<\/li>\n<\/ul>\n1.4 Handling Disconnections<\/h3>\n
\n
\nfrom fastapi import WebSocket, WebSocketDisconnect\n\nasync def websocket_endpoint(websocket: WebSocket):\n await websocket.accept()\n try:\n while True:\n data = await websocket.receive_text()\n print(f\"Received: {data}\")\n await websocket.send_text(f\"Echo: {data}\")\n except WebSocketDisconnect:\n print(\"Client disconnected\")\n<\/pre>\n<\/a>2. Code Example<\/h2>\n
websockets<\/code> library for both client communication and external WebSocket proxying.\npip install fastapi uvicorn websockets\n<\/pre>\n
2.1 FastAPI Server (main.py)<\/h3>\n
\nfrom fastapi import FastAPI, WebSocket, WebSocketDisconnect\nimport websockets\n\napp = FastAPI()\n\n@app.websocket(\"\/ws\")\nasync def websocket_handler(websocket: WebSocket):\n await websocket.accept()\n print(\"Client connected\")\n\n try:\n while True:\n message_type = await websocket.receive_text()\n\n # TEXT MESSAGE FLOW\n if message_type == \"text\":\n data = await websocket.receive_text()\n print(f\"Received text: {data}\")\n await websocket.send_text(f\"Echo: {data}\")\n\n # FILE TRANSFER FLOW\n elif message_type == \"file\":\n print(\"Receiving file...\")\n with open(\"received_file.txt\", \"wb\") as f:\n while True:\n chunk = await websocket.receive_bytes()\n if chunk == b\"EOF\":\n break\n f.write(chunk)\n\n await websocket.send_text(\"File received successfully\")\n\n # PROXY FLOW (external websocket)\n elif message_type == \"proxy\":\n external_uri = \"wss:\/\/echo.websocket.events\"\n\n async with websockets.connect(external_uri) as external_ws:\n client_data = await websocket.receive_text()\n await external_ws.send(client_data)\n\n response = await external_ws.recv()\n await websocket.send_text(f\"External response: {response}\")\n\n except WebSocketDisconnect:\n print(\"Client disconnected\")\n<\/pre>\n\/ws<\/code> WebSocket route, where incoming client connections are accepted using await websocket.accept()<\/code>. Inside an infinite loop, the server first receives a message type indicator (such as “text”, “file”, or “proxy”) to determine how to process the subsequent data. For text messages, it receives a string using receive_text()<\/code>, logs it, and sends back an echoed response. For file transfers, it switches to binary mode, continuously reading chunks using receive_bytes()<\/code> until an EOF<\/code> marker is received, writing the data to a local file. In the proxy flow, the server acts as an intermediary by establishing a connection to an external WebSocket server using the websockets<\/code> library, forwarding client data, receiving a response from the external service, and relaying it back to the client. The entire interaction is wrapped in a try-except<\/code> block to gracefully handle client disconnections using WebSocketDisconnect<\/code>, ensuring stability and proper cleanup of the connection lifecycle.<\/p>\n2.1.1 Run Server<\/h4>\n
\nuvicorn main:app --reload\n<\/pre>\n
main:app<\/code> refers to the app<\/code> instance inside the main.py<\/code> file. The --reload<\/code> flag enables auto-reloading, which is useful during development as the server automatically restarts when code changes are detected. By default, the server runs on http:\/\/127.0.0.1:8000<\/code>, and the WebSocket endpoint becomes available at ws:\/\/127.0.0.1:8000\/ws<\/code>. Once the server is running, it will listen for incoming WebSocket connections and log events such as client connections, messages received, file transfers, and disconnections in the console. Ensure the server is running before starting the client to establish a successful connection.<\/p>\n2.2 Python Client (client.py)<\/h3>\n
\nimport asyncio\nimport websockets\n\nasync def send_text(websocket):\n await websocket.send(\"text\")\n await websocket.send(\"Hello from client!\")\n response = await websocket.recv()\n print(\"Text Response:\", response)\n\nasync def send_file(websocket):\n await websocket.send(\"file\")\n with open(\"sample.txt\", \"rb\") as f:\n while chunk := f.read(1024):\n await websocket.send(chunk)\n await websocket.send(b\"EOF\")\n\n response = await websocket.recv()\n print(\"File Response:\", response)\n\nasync def proxy_message(websocket):\n await websocket.send(\"proxy\")\n await websocket.send(\"Hello external socket!\")\n response = await websocket.recv()\n print(\"Proxy Response:\", response)\n\nasync def main():\n uri = \"ws:\/\/localhost:8000\/ws\"\n\n async with websockets.connect(uri) as websocket:\n await send_text(websocket)\n await send_file(websocket)\n await proxy_message(websocket)\n\nasyncio.run(main())\n<\/pre>\n
asyncio<\/code> and websockets<\/code> libraries to interact with a FastAPI WebSocket server. It defines three separate async functions to handle different communication flows: send_text()<\/code> sends a “text” identifier followed by a string message and waits for an echoed response from the server; send_file()<\/code> initiates a file transfer by sending a “file” identifier, then reads a local file (sample.txt<\/code>) in chunks of 1024 bytes and streams each chunk over the WebSocket, finally sending an EOF<\/code> marker to signal completion and receiving a confirmation response; proxy_message()<\/code> triggers the proxy flow by sending a “proxy” identifier along with a message that the server forwards to an external WebSocket and returns the response. The main()<\/code> function establishes a connection to the WebSocket server at ws:\/\/localhost:8000\/ws<\/code> using an async context manager, ensuring proper connection handling, and sequentially executes all three flows over the same persistent connection. Finally, asyncio.run(main())<\/code> starts the event loop and runs the client, demonstrating how multiple interaction patterns can be efficiently handled over a single WebSocket session.<\/p>\n2.3 Code Run and Output<\/h3>\n
2.3.1 Server Console<\/h4>\n
\nClient connected\nReceived text: Hello from client!\nReceiving file...\nClient disconnected (after completion)\n<\/pre>\n
2.3.2 Client Console<\/h4>\n
\nText Response: Echo: Hello from client!\nFile Response: File received successfully\nProxy Response: External response: Hello external socket!\n<\/pre>\n
2.3.3 File Output<\/h4>\n
\nreceived_file.txt \u2192 contains same content as sample.txt\n<\/pre>\n