pmd-pytcp

What it is and what it does

PyTCP is a complete TCP/IP stack written entirely in Python that runs in user space on TAP/TUN interfaces instead of relying on the kernel. It implements Ethernet II, ARP, IPv4/IPv6 with extension headers, ICMPv4/ICMPv6 (including multicast group membership), DHCPv4/DHCPv6, UDP, and a full RFC 9293 TCP with congestion control (Reno, NewReno, CUBIC), selective acknowledgment, and window scaling. The stack exposes a Berkeley-sockets API that mirrors the standard library socket module, so existing socket code can often run with minimal changes.

You can embed PyTCP directly in your Python process (calling stack.init(), stack.start(), then creating sockets) or run it as a daemon in a separate process and connect to it via an AF_UNIX control socket from client processes. The daemon model lets multiple processes share a single stack instance without each one needing to own the TAP/TUN interface. The implementation is fully typed, thread-safe for multi-interface setups, and designed to match Linux kernel behavior where RFCs are ambiguous. It ships with three independently published distributions: pmd-net-addr (address types), pmd-net-proto (packet parsing), and pmd-pytcp (the running stack).

Use it for:

• Embedded network simulation or testing: run a full TCP/IP stack in a test harness without kernel privileges or system configuration.
• Custom protocol development: build and test new transport or application protocols on top of a controllable, inspectable stack.
• Network emulation or sandbox environments: isolate application network behavior in user space for security or reproducibility.
• Educational or reference implementation: study RFC-compliant TCP/IP behavior with readable, auditable Python source code.
• Daemon-based multi-process networking: share a single stack instance across multiple client processes via IPC.
• TAP/TUN-based VPN or overlay networking: implement custom network overlays or tunneling without kernel module development.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pure-Python TCP/IP stack (Ethernet through RFC 9293 TCP) that runs in user space on TAP/TUN interfaces, embeddable as a library or daemon, with a Berkeley-sockets API.

Yes, with conditions. Install if you need a pure-Python, controllable TCP/IP stack for testing, simulation, or custom protocol work and can accept GPL-3.0-or-later licensing. The low install friction, active maintenance, and zero external dependencies (only internal PyTCP modules) make it straightforward to add. However, it is Alpha-status software; expect API changes and verify performance and stability for your use case before relying on it in production. Requires Linux and root/CAP_NET_ADMIN for interface setup.

Install

pmd-pytcp on PyPI

pip install pmd-pytcp

uv add pmd-pytcp

poetry add pmd-pytcp

Installing pmd-pytcp

Before you install

Low friction: three runtime dependencies (pmd-net-addr, pmd-net-proto, typing_extensions), all published by the same project. Active maintenance with a commit on 2026-08-10 and 376 repository stars. Alpha status (Development Status :: 3) means the API may still shift.

License in practice

GPL-3.0-or-later (copyleft): any code that links this library must be distributed under a compatible open-source license. Proprietary or closed-source projects cannot use it without a separate commercial license.

Quickstart

# In-process stack
from pmd_pytcp import socket, stack

stack.init()
stack.start()
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(("10.0.1.1", 7))
sock.send(b"hello")
data = sock.recv(5)
sock.close()
stack.stop()

# Or daemon mode (separate process):
# Terminal 1: python -m pmd_pytcp.daemon --ipc-socket /tmp/pmd_pytcp.sock
# Terminal 2:
from pmd_pytcp.client import connect
from pmd_pytcp.socket import AddressFamily, SocketType
with connect(socket_path="/tmp/pmd_pytcp.sock") as client:
    sock = client.socket(AddressFamily.INET4, SocketType.STREAM)
    sock.connect(("10.0.1.1", 7))

Requires root or CAP_NET_ADMIN to create and configure TAP/TUN interfaces. Python >=3.9 required. Linux only (POSIX::Linux classifier).

Verify before relying

• Performance characteristics (throughput, latency) compared to kernel stack or other implementations.
• Stability and production readiness beyond Alpha status; known limitations or edge cases in RFC compliance.
• Multicast and IPv6 feature completeness (MLDv2/IGMP mentioned but not fully detailed).
• Scalability limits (number of concurrent sockets, interfaces, or packet throughput).

Package facts

Evidence: pmd_pytcp-0.3.7-py3-none-any.whl

Keywords: pmd_pytcp, stack, networking, tcp, ip, ipv4, ipv6, arp, ethernet, icmp

Tags

More Networking packages