{"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":"python","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,"search_vec":"'0.4.1':37 'adapt':58 'allow':12 'appear':39 'communic':19 'compat':47 'current':33 'domain':22 'extend':25 'focus':43 'function':27 'http':16,30,52 'infrequ':42 'librari':10,17 'mainten':45 'network':57 'newer':49 'popular':14 'python':9 'releas':38 'request':2,5,15,26,50,53 'requests-unixsocket':1,4 'socket':23,56 'stabl':34 'support':29 'unix':21,55 'unix-socket':54 'unixsocket':3,6 'url':31 'version':35,51","created_at":"2026-04-11T01:41:11.858859+00:00","updated_at":"2026-04-17T14:12:04.552927+00:00","problems":[{"fix":"Install the library using pip: `pip install requests-unixsocket`","cause":"The `requests-unixsocket` library has not been installed in the Python environment, or the environment where the code is being run does not have access to the installed package.","error":"ModuleNotFoundError: No module named 'requests_unixsocket'"},{"fix":"Ensure the server process is running and listening on the specified UNIX domain socket. Verify that the socket file path is correct in the URL and that the Python process has read/write permissions for the socket file and its parent directories.","cause":"The target UNIX domain socket file specified in the URL does not exist, the server application listening on that socket is not running, or the current user lacks the necessary permissions to access the socket file.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))"},{"fix":"Use `requests_unixsocket.Session()` for explicit usage, or call `requests_unixsocket.monkeypatch()` at the start of your script to enable `http+unix://` URLs with standard `requests` calls.\n\n**Explicit usage:**\n```python\nimport requests_unixsocket\nsession = requests_unixsocket.Session()\nr = session.get('http+unix://%2Fvar%2Frun%2Fdocker.sock/info')\n```\n\n**Monkeypatching:**\n```python\nimport requests\nimport requests_unixsocket\nrequests_unixsocket.monkeypatch()\nr = requests.get('http+unix://%2Fvar%2Frun%2Fdocker.sock/info')\n```","cause":"The `requests-unixsocket` library was imported, but its functionality was not activated either by using a `requests_unixsocket.Session()` object or by globally monkeypatching the `requests` library.","error":"requests.exceptions.MissingSchema: Invalid URL \"http+unix://...\": No schema supplied. Perhaps you meant http://http+unix://...?"},{"fix":"import requests_unixsocket\nrequests_unixsocket.monkeypatch()\nrequests.get('http+unix://%2Ftmp%2Ftest.sock/endpoint')","cause":"The `requests-unixsocket` adapter was not registered with `requests`, either by calling `requests_unixsocket.monkeypatch()` or manually mounting a `UnixAdapter`.","error":"requests.exceptions.InvalidSchema: No connection adapters were found for 'http+unix://%2Ftmp%2Ftest.sock/endpoint'"},{"fix":"import requests_unixsocket\nrequests_unixsocket.monkeypatch()\nrequests.get('http+unix://%2Ftmp%2Ftest.sock/endpoint')","cause":"The URL provided for the UNIX socket connection does not use the required `http+unix://` schema, or the socket path is not properly encoded.","error":"requests.exceptions.MissingSchema: Invalid URL '/tmp/test.sock': No schema supplied. Perhaps you meant http:////tmp/test.sock?"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/msabramo/requests-unixsocket","docs":null,"changelog":null,"pypi":"https://pypi.org/project/requests-unixsocket/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}