{"id":2749,"library":"requests-unixsocket","title":"requests-unixsocket","description":"requests-unixsocket is a Python library that allows the popular `requests` HTTP library to communicate over UNIX domain sockets. It extends `requests`' functionality to support `http+unix://` URLs. The current stable version is 0.4.1. Releases appear to be infrequent, focusing on maintenance and compatibility with newer `requests` versions.","status":"active","version":"0.4.1","language":"en","source_language":"en","source_url":"https://github.com/msabramo/requests-unixsocket","tags":["http","requests","unix-socket","networking","adapter"],"install":[{"cmd":"pip install requests-unixsocket","lang":"bash","label":"Install latest stable"}],"dependencies":[{"reason":"Core library extended by requests-unixsocket for HTTP functionality.","package":"requests","optional":false},{"reason":"Underlying HTTP client library used by requests and implicitly by requests-unixsocket.","package":"urllib3","optional":false}],"imports":[{"note":"Use the specialized Session for explicit UNIX socket handling.","wrong":"import requests; s = requests.Session()","symbol":"Session","correct":"from requests_unixsocket import Session"},{"note":"Applies global monkeypatching for `requests.get()` to handle `http+unix://` URLs.","symbol":"monkeypatch","correct":"import requests_unixsocket; requests_unixsocket.monkeypatch()"}],"quickstart":{"code":"import requests_unixsocket\nimport os\n\n# Example for Docker daemon socket (adjust path if needed)\ndocker_socket_path = '/var/run/docker.sock' # or os.environ.get('DOCKER_SOCKET', '/var/run/docker.sock')\n\n# Ensure the socket path exists for a runnable example\n# In a real scenario, Docker or another service would create this.\n# For this quickstart, we'll just check if it exists or use a dummy.\nif not os.path.exists(docker_socket_path):\n    print(f\"Warning: Docker socket not found at {docker_socket_path}. Quickstart might not connect.\")\n    # Fallback to a non-existent path for structure, but it will fail.\n    docker_socket_path = '/tmp/nonexistent_socket.sock'\n\n# Explicit Session usage\nsession = requests_unixsocket.Session()\n# The socket path must be percent-encoded in the URL host part\nencoded_socket_path = requests_unixsocket.requests.compat.quote_plus(docker_socket_path)\nurl = f'http+unix://{encoded_socket_path}/info'\n\ntry:\n    response = session.get(url, timeout=5)\n    response.raise_for_status() # Raise an exception for HTTP errors\n    print(\"Explicit Session usage successful!\")\n    print(f\"Status Code: {response.status_code}\")\n    print(f\"JSON Response Keys: {list(response.json().keys())[:5]}...\")\nexcept requests_unixsocket.requests.exceptions.ConnectionError as e:\n    print(f\"Connection Error: Could not connect to UNIX socket at {docker_socket_path}. Is a service listening there? (Error: {e})\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\n# --- Alternative: Monkeypatching (affects global requests behavior) ---\n# This is generally discouraged for libraries, but shown for completeness.\n# with requests_unixsocket.monkeypatch():\n#     try:\n#         response_mp = requests_unixsocket.requests.get(url, timeout=5)\n#         response_mp.raise_for_status()\n#         print(\"\\nMonkeypatching usage successful!\")\n#         print(f\"Status Code: {response_mp.status_code}\")\n#         print(f\"JSON Response Keys: {list(response_mp.json().keys())[:5]}...\")\n#     except requests_unixsocket.requests.exceptions.ConnectionError as e:\n#         print(f\"\\nMonkeypatching Connection Error: Could not connect to UNIX socket at {docker_socket_path}. (Error: {e})\")\n#     except Exception as e:\n#         print(f\"\\nAn unexpected error occurred with monkeypatching: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `requests-unixsocket` in two ways: explicitly via `requests_unixsocket.Session` (recommended) and implicitly via `requests_unixsocket.monkeypatch()`. It attempts to connect to a common Docker UNIX domain socket to retrieve system information, handling potential connection errors. The socket path must be URL-percent-encoded."},"warnings":[{"fix":"Ensure `requests-unixsocket` is updated to the latest version. If issues persist, consider pinning `requests` to a compatible older version or checking the `requests-unixsocket` GitHub issues for workarounds or upcoming fixes. A fork, `requests-unixsocket2`, emerged due to past incompatibilities, indicating this is a recurring concern.","message":"Updates to the upstream `requests` library can sometimes introduce breaking changes that affect `requests-unixsocket`, particularly related to internal adapter interfaces. While `requests-unixsocket` aims to maintain compatibility, rapid `requests` releases may temporarily break functionality.","severity":"breaking","affected_versions":"All versions, potentially with newer `requests` versions."},{"fix":"Always use `requests.compat.quote_plus()` or `urllib.parse.quote_plus()` to encode the UNIX socket path before constructing the `http+unix://` URL.","message":"UNIX socket paths in URLs must be URL-percent-encoded (e.g., `/var/run/docker.sock` becomes `%2Fvar%2Frun%2Fdocker.sock`). Failure to encode correctly will result in incorrect URL parsing and connection errors.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Prefer creating an explicit `requests_unixsocket.Session()` instance for better isolation and control. If monkeypatching is necessary, limit its scope using a `with requests_unixsocket.monkeypatch():` context manager.","message":"Using `requests_unixsocket.monkeypatch()` globally alters the default behavior of `requests.get()` and `requests.Session()` (for default sessions). This can lead to unexpected side effects in other parts of an application or library that rely on standard `requests` behavior.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Always explicitly set the `timeout` parameter in your `session.get()` or `session.post()` calls to ensure consistent and predictable behavior.","message":"The default timeout for `requests-unixsocket` connections (historically 60 seconds) might differ from the default behavior of `requests` (which has no default timeout). This can lead to unexpected blocking or timeout behavior if not explicitly set.","severity":"gotcha","affected_versions":"Potentially all versions prior to `requests` aligning its own timeout handling with adapters; user-specified timeouts are always respected."},{"fix":"Ensure that if abstract namespace sockets are used, the application is deployed on a Linux environment. For cross-platform compatibility, prefer file-system based UNIX domain sockets or alternative IPC mechanisms.","message":"Abstract namespace sockets (e.g., `http+unix://\\0test_socket/`) are a Linux-specific feature and will not work on other operating systems like macOS or Windows.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}