Skip to content
Tutorials Center
My learning

Topics

Lesson 43 of 79 Β· Transport Layer

Socket Programming in Python

Write TCP and UDP clients and servers with Python's socket module, handle many clients with threads and select, and frame messages with a length prefix.

The previous lesson introduced the socket API with Node.js. Python's standard socket module exposes the very same operating-system calls (socket, bind, listen, accept, connect, send, recv), so what you learn here carries over to C, Java, Go and every other language. Python is a popular choice for network scripts, test tools and small servers because the code is short and the module ships with the interpreter.

There is one practical catch for this site. The Python runner in your browser (Pyodide) is sandboxed and cannot open sockets. So the real socket programs in this lesson are shown as read-only code that you can copy to your own machine, and the examples you can run live use a small loopback simulator that behaves like a socket pair. The simulator is honest about the one thing that matters most: a TCP stream delivers bytes, not messages.

A TCP echo server and client

This is the smallest useful TCP server. It handles one client at a time and sends back whatever it receives. Save it as echo_server.py on your own computer.

Python
import socket

HOST, PORT = "127.0.0.1", 5050

with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind((HOST, PORT))
    server.listen()
    print("listening on", server.getsockname())
    while True:
        conn, addr = server.accept()          # blocks until a client connects
        with conn:
            print("connection from", addr)
            while True:
                data = conn.recv(4096)        # blocks until bytes arrive
                if not data:                  # b"" means the peer closed
                    break
                conn.sendall(data)

The pieces map directly onto the socket API:

  • AF_INET selects IPv4 (AF_INET6 selects IPv6) and SOCK_STREAM selects TCP.
  • SO_REUSEADDR lets you restart the server immediately instead of waiting for old connections in TIME_WAIT to disappear.
  • bind attaches the socket to an address and port. 127.0.0.1 accepts only local clients; 0.0.0.0 accepts connections on every interface.
  • listen turns the socket into a listening socket, and accept returns a new socket for each client, plus the client's address.
  • recv(4096) returns up to 4,096 bytes. An empty bytes object means the other side closed the connection.
  • sendall keeps sending until everything is written. Plain send may write only part of the data and returns how much it wrote.

The matching client:

Python
import socket

with socket.create_connection(("127.0.0.1", 5050)) as sock:
    sock.sendall(b"hello, server")
    print(sock.recv(4096))        # b'hello, server'

create_connection resolves the name (using DNS if needed), tries each address it finds and performs the three-way handshake. Always send and receive bytes; use .encode() and .decode() to convert text.

sequenceDiagram
    participant S as Server
    participant C as Client
    S->>S: socket(), bind(), listen()
    C->>C: socket()
    C->>S: connect() (SYN, SYN-ACK, ACK)
    S->>S: accept() returns a new socket
    C->>S: sendall("hello")
    S->>C: sendall("hello")
    C->>S: close() (FIN)
    S->>S: recv() returns b""

The life of one TCP connection as seen through the Python socket calls.

Messages do not exist in TCP

The most common beginner bug is to assume that one send on one side matches one recv on the other. It does not. TCP delivers a stream of bytes. The network and the operating system may split your data into several segments, or merge several sends into one, so recv can return half a message, exactly one message, or two and a half.

The simulator below imitates this. SimStream has the same sendall and recv methods as a connected socket, and it hands out bytes in random chunks, the way a real network might. Three messages go in; look at what comes out.

Python TCP is a byte stream (loopback simulator)

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The bytes are identical and in order (TCP guarantees that), but the pieces are not. Your protocol must therefore mark where each message begins and ends. There are three common ways:

Technique How it works Example
Delimiter A special byte or sequence ends each message Newline in SMTP and line-based chat; \r\n\r\n ends HTTP headers
Fixed length Every message has the same size Some binary sensor protocols
Length prefix A header states how many bytes follow TLS records, many database protocols

A length-prefixed protocol

A length prefix is the most robust choice because the payload may contain any bytes at all. The sender writes a 4-byte big-endian length (struct.pack("!I", n)), then the payload. The receiver first reads exactly 4 bytes, decodes the length, then reads exactly that many bytes. "Exactly" needs a loop, because recv(n) may return fewer than n bytes.

Python Length-prefixed messages over the simulated stream

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the second message contains a newline and the last one contains non-ASCII text, and neither is a problem: the receiver never scans for a delimiter, it just counts bytes. In a real server you should also reject absurd lengths (for example above a few megabytes), or one bad header could make the program wait for gigabytes.

Handling many clients

The echo server above can serve only one client at a time: while it sits in recv for client A, client B waits in the accept queue. There are three standard ways to fix that.

One thread per connection. Easy to write and fine for dozens or a few hundred clients:

Python
import socket
import threading

def handle(conn, addr):
    with conn:
        while data := conn.recv(4096):
            conn.sendall(data)

with socket.create_server(("127.0.0.1", 5050)) as server:
    while True:
        conn, addr = server.accept()
        threading.Thread(target=handle, args=(conn, addr), daemon=True).start()

socket.create_server does socket, SO_REUSEADDR, bind and listen in one call. Threads blocked on I/O do not hold Python's global interpreter lock, so this pattern works well for network code. The cost is memory (every thread has a stack) and the care needed when threads share data.

One thread with select. Instead of blocking on one socket, ask the operating system which sockets are ready and handle only those. The selectors module gives a portable wrapper over select, epoll and kqueue:

Python
import selectors
import socket

sel = selectors.DefaultSelector()
server = socket.create_server(("127.0.0.1", 5050))
server.setblocking(False)
sel.register(server, selectors.EVENT_READ)

while True:
    for key, _ in sel.select():
        sock = key.fileobj
        if sock is server:
            conn, _ = server.accept()
            conn.setblocking(False)
            sel.register(conn, selectors.EVENT_READ)
        else:
            data = sock.recv(4096)
            if data:
                sock.send(data)       # a real server buffers partial writes
            else:
                sel.unregister(sock)
                sock.close()

This event loop is how Node.js, nginx and Redis handle thousands of connections on one thread. It is more work to write because you cannot simply block while waiting for the rest of a message; you must keep per-connection state.

asyncio. The standard asyncio.start_server gives you the event-loop efficiency with ordinary-looking await code, and is usually the best choice for new Python servers. It uses the same selectors underneath.

flowchart LR
    A["Blocking, one client at a time"] --> B["Thread per client<br/>simple, limited scale"]
    A --> C["select / selectors<br/>one thread, state machines"]
    C --> D["asyncio<br/>await syntax over an event loop"]

Three ways to serve many connections; the right choice depends on how many clients you expect.

UDP sockets

UDP has no connection, so there is no listen, accept or connect in the usual sense. Each sendto is one datagram, and each recvfrom returns exactly one datagram together with the sender's address. This is the read-only UDP echo server:

Python
import socket

with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
    sock.bind(("127.0.0.1", 5051))
    while True:
        data, addr = sock.recvfrom(2048)
        sock.sendto(data.upper(), addr)

and its client:

Python
import socket

with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
    sock.settimeout(1.0)                      # UDP never retransmits for you
    sock.sendto(b"ping", ("127.0.0.1", 5051))
    try:
        data, _ = sock.recvfrom(2048)
        print(data)
    except socket.timeout:
        print("no reply: lost, or nobody is listening")

Compared with TCP, message boundaries are preserved, but a datagram can be lost, duplicated or reordered, and nothing tells you. If your reply must arrive, you need your own timeout and retry logic. See UDP for the protocol itself.

The simulator below shows two UDP-specific traps: a lost datagram, and a receive buffer smaller than the datagram, which silently truncates it (on most systems the rest is discarded).

Python UDP datagrams: boundaries, loss and truncation

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical advice

  • Always set timeouts on client sockets (sock.settimeout(5)), otherwise a dead peer can block your program forever.
  • Close what you open. Use with blocks so sockets are closed even when exceptions occur.
  • Never trust the network. Check lengths, handle ConnectionResetError and BrokenPipeError, and decode text defensively.
  • Test on loopback first. Connecting to 127.0.0.1 removes the real network from the problem, which makes bugs reproducible.
  • Prefer higher-level libraries in production. Use http.server, asyncio or a framework for real services. Raw sockets are for learning, custom protocols and tools.

If a program that works on 127.0.0.1 fails from another machine, check that you bound to 0.0.0.0 (or the right interface) and that a firewall allows the port.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. A client calls sendall() three times with short messages. How many recv() calls will the server need on a TCP socket?

    TCP preserves the byte order but not message boundaries. One recv can return part of a message or several messages together.
  2. 2. What does recv() returning an empty bytes object mean on a TCP socket?

    A blocking recv waits until data arrives. b"" is the end-of-stream signal, produced when the other side sends its FIN.
  3. 3. Why does a length-prefix protocol use a loop such as recv_exact?

    recv(n) means up to n bytes. To get exactly n you must keep reading until you have them all.
  4. 4. Which statement about UDP sockets is correct?

    UDP preserves datagram boundaries. If the buffer is smaller than the datagram, the excess is discarded. There is no retransmission and no listen/accept.
  5. 5. Which approach lets one thread watch many sockets and handle only the ones that are ready?

    select (and selectors, epoll, kqueue) tells you which sockets are ready to read or write, so a single thread never blocks on an idle one.

Summary

  • Python's socket module wraps the same system calls as every other language: bind, listen, accept, connect, send, recv.
  • A TCP socket carries a byte stream. recv returns up to the requested size, so you must frame messages with delimiters or a length prefix and read exactly the bytes you need.
  • Serve many clients with threads, with select/selectors on one thread, or with asyncio.
  • UDP keeps datagram boundaries but gives no delivery guarantee, so add timeouts and retries yourself, and size the receive buffer for the largest datagram.
  • Pyodide cannot open sockets, so this lesson's live examples used a simulator; the real programs run on your own machine.

Next, see why even TCP's neat ordering becomes a problem on modern networks, and what replaces it, in QUIC, SCTP and Modern Transports.