---
id: proxy-protocol
version: "0.11.3"
license: ## The MIT License (MIT) Copyright (c) 2021 Ian Good Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),… (full text in the JSON record)
license_treatment: permissive
maintenance: dormant
---

# proxy-protocol — PROXY protocol library with asyncio server implementation

License: permissive · Maintenance: dormant · Downloads: 1.9M/mo

## 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 above — 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

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

- License: ## The MIT License (MIT) Copyright (c) 2021 Ian Good Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 1.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

proxy protocol asyncio, haproxy protocol parser, detect original client ip, proxy protocol v1 v2, asyncio server proxy headers, load balancer connection info, proxy protocol implementation, asyncio, proxy-protocol, networking

[View on SkillFed](https://skillfed.io/packages/proxy-protocol) · [View on PyPI](https://pypi.org/project/proxy-protocol/)