{"id":6420,"library":"proxy-py","title":"Proxy.py","description":"Proxy.py is a lightweight, dependency-optional, and pluggable framework for building fast proxy servers, web servers, and pub/sub systems. It supports HTTP, HTTPS, TLS interception, DNS-over-HTTPS, and can function as a reverse or forward proxy. Currently at version 2.4.10, the library maintains an active release cadence with frequent updates and new features.","status":"active","version":"2.4.10","language":"en","source_language":"en","source_url":"https://github.com/abhinavsingh/proxy.py","tags":["proxy","http","https","network","server","framework","tls","plugin","reverse-proxy","forward-proxy","web-server"],"install":[{"cmd":"pip install proxy.py","lang":"bash","label":"Basic Install"},{"cmd":"pip install proxy.py[dashboard,tls,grout,ssh]","lang":"bash","label":"Install with All Extras"}],"dependencies":[{"reason":"Required for TLS interception, dashboard, and HTTP metrics features. Installed with '[tls]', '[dashboard]', '[http-metrics]' extras.","package":"cryptography","optional":true},{"reason":"System-level OpenSSL utility is required for TLS interception to generate certificates. The 'openssl' executable must be in your PATH or specified via `--openssl` flag.","package":"OpenSSL","optional":true},{"reason":"Required for SSH/SFTP proxying capabilities. Installed with '[ssh]' extra.","package":"paramiko","optional":true}],"imports":[{"symbol":"Proxy","correct":"from proxy.py import Proxy"},{"note":"Plugin paths changed over time; always refer to the specific module path, e.g., `proxy.py.http.proxy.HttpProxyPlugin`","wrong":"from proxy.py.plugins import HttpProxyPlugin","symbol":"HttpProxyPlugin","correct":"from proxy.py.http.proxy import HttpProxyPlugin"},{"note":"Provides access to core HTTP components and utilities.","symbol":"http","correct":"from proxy.py import http"}],"quickstart":{"code":"import os\nfrom proxy.py import Proxy\n\nif __name__ == '__main__':\n    # Example: Run a basic HTTP proxy on localhost:8899\n    args = [\n        '--hostname', '127.0.0.1',\n        '--port', '8899',\n        '--num-workers', '1', # For a simple quickstart\n        '--disable-web-server', # Disable built-in web server if only proxy is needed\n        '--plugins', 'proxy.py.http.proxy.HttpProxyPlugin' # Explicitly enable HTTP proxy\n    ]\n\n    print(f\"Starting HTTP proxy on 127.0.0.1:8899...\")\n    print(\"Use Ctrl+C to stop.\")\n\n    try:\n        # Proxy.main() takes arguments similar to command-line execution\n        with Proxy.main(args):\n            # The proxy runs in separate worker threads within the context manager.\n            # Keep the main thread alive to allow the proxy to run.\n            import time\n            while True:\n                time.sleep(1) \n    except KeyboardInterrupt:\n        print(\"\\nProxy stopped.\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically start a basic HTTP forward proxy on `127.0.0.1:8899` using `proxy.py`. The `Proxy.main()` method is used with a list of arguments, mimicking command-line input. The `with` statement ensures proper resource management. The `time.sleep` loop keeps the main thread alive while the proxy runs in its own threads, allowing it to handle requests until a `KeyboardInterrupt` (Ctrl+C) is received."},"warnings":[{"fix":"If implementing custom SSL handling, migrate to `SSLContext.wrap_socket`. The library's internal components generally handle this automatically in recent versions.","message":"Usage of `ssl.wrap_socket` is deprecated in favor of `SSLContext.wrap_socket` for better security and future compatibility.","severity":"deprecated","affected_versions":">=2.4.7"},{"fix":"Ensure `pip install proxy.py[tls]` is used. Verify `openssl` is installed and accessible. For production, manage certificates securely and consider the `--insecure-tls-interception` flag only for development/testing.","message":"TLS (HTTPS) interception requires the `cryptography` Python package and a functional `openssl` command-line utility in your system's PATH. Certificate management (generating root CA, signing server certificates) is also crucial and must be properly configured.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Familiarize yourself with the plugin API (e.g., `HttpProxyPlugin`, `WebServerPlugin`, `GroutPlugin`). Ensure plugins are listed correctly in the `--plugins` argument or passed programmatically when initializing `Proxy`.","message":"The library heavily relies on a pluggable architecture. To implement custom logic (e.g., modifying requests, logging, authentication), you must create and register plugins correctly. Misconfigured or missing plugins can lead to unexpected proxy behavior or unhandled requests.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the Grout documentation thoroughly. Ensure correct hostnames, ports, and (if applicable) authentication are configured. Be mindful of security implications when exposing local services to the internet.","message":"The Grout feature, which offers ngrok-like functionality for exposing local services, requires specific configuration and understanding of its tunneling mechanics. Improper setup can expose services insecurely or fail to establish tunnels.","severity":"gotcha","affected_versions":">=2.4.4"},{"fix":"Always install with the necessary extras, e.g., `pip install proxy.py[dashboard,tls]`, to ensure all desired features and their dependencies are available.","message":"Many features (e.g., dashboard, metrics, SSH proxy) are gated behind optional `extras` during installation. If functionality is missing or imports fail, it's often due to not installing the required extras.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}