proxy-protocol

What it is and what it does

proxy-protocol is a Python library that implements the PROXY protocol specification, enabling asyncio servers to read and interpret connection headers sent by proxies and load balancers. When traffic passes through a reverse proxy or load balancer, the original client's IP address and port are typically lost; the PROXY protocol solves this by prepending a header to the connection that encodes the original source and destination. This library detects and parses both PROXY protocol v1 (text-based) and v2 (binary) formats, extracting the original connection information so your server can log or act on the true client address.

Integration is designed to be straightforward with asyncio servers. The package depends only on typing-extensions and supports Python 3.8, 3.9, 3.10, 3.11, and 3.12. It includes reference server implementations and supports configuration-driven protocol selection—detect automatically, enforce a specific version, or disable the protocol entirely.

Use it for:

• Logging true client IPs in a web service behind a reverse proxy or load balancer.
• Proxying connections between services while preserving original connection metadata.
• Building a load balancer or proxy that needs to forward connection info to backend servers.
• Debugging network topology by inspecting original vs. proxied connection information.
• Integrating with HAProxy or other proxies that emit PROXY protocol headers.

Worth the install?

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

Parses and handles the PROXY protocol (v1 and v2) for asyncio-based servers, allowing detection of original client connection information when traffic passes through proxies or load balancers.

Yes, if you need PROXY protocol support in an asyncio server and are comfortable with dormant maintenance. The library is stable (Alpha status), has no known vulnerabilities, and low install friction. However, verify that the last update (2024-04-27) and lack of recent activity align with your support expectations—if you need active maintenance or rapid bug fixes, evaluate alternatives or plan to maintain a fork.

Install

proxy-protocol on PyPI

pip install proxy-protocol

uv add proxy-protocol

poetry add proxy-protocol

Installing proxy-protocol

Before you install

Low install friction—pure Python wheel with only typing-extensions as a runtime dependency. Maintenance is dormant (last commit 2024-04-27, 839 days ago), though the repository remains active and the package is classified as Alpha.

License in practice

MIT license (permissive) permits use, modification, and redistribution with minimal restrictions, making it safe for commercial and private projects.

Quickstart

pip install proxy-protocol

from proxy_protocol import ProxyProtocol
import asyncio

pp_detect = ProxyProtocol()
server = await asyncio.start_server(callback, 'localhost', 10007)

Requires Python ~=3.8 or later; intended for use with asyncio.start_server-based applications.

Verify before relying

• Whether dormant maintenance (last commit 2024-04-27) signals end-of-life or stable maturity for this use case.
• Real-world performance characteristics with high-throughput proxy scenarios.
• Compatibility with modern proxy/load-balancer implementations beyond the HAProxy specification.

Package facts

Evidence: proxy_protocol-0.11.3-py3-none-any.whl

Tags

More Internet packages