{"id":9817,"library":"httpdbg","title":"httpdbg: HTTP Debugging Proxy","description":"httpdbg is a simple Python tool designed to debug HTTP(S) client and server requests. It functions as a local proxy, capturing and displaying all outgoing and incoming HTTP traffic in a user-friendly web interface. Currently at version 2.1.6, it receives regular updates for bug fixes and minor feature enhancements, maintaining active development.","status":"active","version":"2.1.6","language":"en","source_language":"en","source_url":"https://github.com/cle-b/httpdbg","tags":["http","https","debugging","proxy","network","requests","httpx","http2"],"install":[{"cmd":"pip install httpdbg","lang":"bash","label":"Install httpdbg"}],"dependencies":[],"imports":[{"note":"The `httpdbg` module is typically imported to access its `start()` and `stop()` functions.","symbol":"httpdbg","correct":"from httpdbg import httpdbg"}],"quickstart":{"code":"import requests\nfrom httpdbg import httpdbg\nimport os\n\n# Start the httpdbg proxy\nhttpdbg.start()\nprint(f\"httpdbg UI available at: http://127.0.0.1:{httpdbg.port}\")\n\n# Configure requests to use the proxy\nproxies = {\n    'http': f'http://127.0.0.1:{httpdbg.port}',\n    'https': f'http://127.0.0.1:{httpdbg.port}'\n}\nos.environ['HTTP_PROXY'] = proxies['http'] # For clients that respect env vars\nos.environ['HTTPS_PROXY'] = proxies['https']\n\ntry:\n    # Make an HTTP request that will be captured\n    print(\"Making a request...\")\n    response = requests.get('http://httpbin.org/get', proxies=proxies, timeout=5)\n    response.raise_for_status()\n    print(f\"Request successful: {response.status_code}\")\n    print(\"Check the httpdbg UI for captured request details.\")\nexcept requests.exceptions.RequestException as e:\n    print(f\"Request failed: {e}\")\nfinally:\n    # Stop the httpdbg proxy\n    httpdbg.stop()\n    print(\"httpdbg stopped.\")\n    # Clean up environment variables\n    del os.environ['HTTP_PROXY']\n    del os.environ['HTTPS_PROXY']\n","lang":"python","description":"This quickstart demonstrates how to programmatically start and stop the httpdbg proxy, and then make a simple HTTP request using the `requests` library, ensuring it routes through the proxy for debugging. The environment variables are set to help other libraries (like `httpx`) automatically pick up the proxy."},"warnings":[{"fix":"Review existing HTTP client configurations and test suites, especially those interacting with HTTP/2 endpoints, for unexpected behavior. Consult httpdbg documentation for any new configuration options related to HTTP/2.","message":"Version 2.0.0 introduced HTTP/2 support. While largely compatible, this major version bump could introduce subtle behavioral changes for applications or test suites that implicitly relied on HTTP/1.x characteristics or specific internal proxy behaviors. Always test thoroughly when upgrading to v2.0.0 or later.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your HTTP client (e.g., `requests`, `httpx`, `urllib`) is explicitly configured to use the `httpdbg` proxy. This often involves setting `HTTP_PROXY` and `HTTPS_PROXY` environment variables to `http://127.0.0.1:5000` (or your chosen port), or passing a `proxies` dictionary to the client functions/sessions.","message":"Requests are not appearing in the httpdbg UI because your application is not using the proxy.","severity":"gotcha","affected_versions":"All"},{"fix":"If you encounter an 'Address already in use' error, start `httpdbg` on an alternative port, e.g., `httpdbg.start(port=8000)`. You will then need to configure your client to use this new port for the proxy.","message":"The default port (5000) used by httpdbg is already in use, causing startup failures.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Make sure to set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to `http://127.0.0.1:5000` (or your custom port), or explicitly pass `proxies={'http': '...', 'https': '...'}` to your HTTP client library.","cause":"Your HTTP client is not configured to send requests through the httpdbg proxy.","error":"Requests are not showing up in the httpdbg UI"},{"fix":"Stop the conflicting process, or start httpdbg on a different port using `httpdbg.start(port=XXXX)` from Python, or `httpdbg --port XXXX` from the command line.","cause":"Another application or process is already listening on the default httpdbg port (5000) or the port you specified.","error":"OSError: [Errno 98] Address already in use"},{"fix":"Run `pip install httpdbg`. If already installed, check `pip list` and ensure there isn't a file named `httpdbg.py` or a directory named `httpdbg` in your current working directory or `PYTHONPATH` that might be conflicting.","cause":"The `httpdbg` library is not installed in your current Python environment, or there's a local file/directory shadowing the installed package.","error":"ModuleNotFoundError: No module named 'httpdbg'"}]}