{"id":4743,"library":"requests-unixsocket2","title":"requests-unixsocket2","description":"requests-unixsocket2 allows the popular 'requests' HTTP library to communicate over UNIX domain sockets. It is a maintained fork of the original 'requests-unixsocket' project, created to ensure compatibility with recent versions of 'requests' and 'urllib3'. The current version is 1.0.1, with releases typically occurring as needed to address compatibility issues or bug fixes.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/thelabnyc/requests-unixsocket2","tags":["http","unix socket","requests","networking"],"install":[{"cmd":"pip install requests-unixsocket2","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionality relies on and extends the 'requests' library.","package":"requests","optional":false}],"imports":[{"note":"Commonly imported directly as 'Session' for explicit usage.","wrong":"import requests_unixsocket.Session","symbol":"Session","correct":"from requests_unixsocket import Session"},{"note":"The monkeypatch function is directly under the 'requests_unixsocket' module.","wrong":"requests.monkeypatch()","symbol":"monkeypatch","correct":"from requests_unixsocket import monkeypatch"}],"quickstart":{"code":"import requests_unixsocket\nimport json\nimport os\n\n# Example: Connect to a hypothetical service via a UNIX domain socket.\n# Replace '/tmp/my_service.sock' with your actual socket path and '/info' with your API endpoint.\n# The socket path must be URL-encoded, e.g., '/' becomes '%2F'.\n\n# For demonstration purposes, use an environment variable or a common placeholder.\n# In a real application, ensure the service is running and listening on this socket.\nunix_socket_path = os.environ.get('UNIX_SOCKET_PATH', '/tmp/my_service.sock')\nencoded_unix_socket_path = unix_socket_path.replace(\"/\", \"%2F\")\n\nsession = requests_unixsocket.Session()\ntry:\n    # Construct the URL using the 'http+unix://' scheme\n    response = session.get(f'http+unix://{encoded_unix_socket_path}/info')\n    response.raise_for_status() # Raises an HTTPError for bad responses (4xx or 5xx)\n    print(\"Response from UNIX socket service:\")\n    print(json.dumps(response.json(), indent=2))\nexcept requests_unixsocket.exceptions.ConnectionError as e:\n    print(f\"Could not connect to UNIX socket at {unix_socket_path}: {e}\")\n    print(\"Please ensure a service is running and listening on this socket.\")\nexcept json.JSONDecodeError:\n    print(f\"Received non-JSON response or empty response from {unix_socket_path}. Status: {response.status_code}\")\n    print(f\"Response text: {response.text}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to make an HTTP GET request to a service listening on a UNIX domain socket using an explicit `Session` object. The socket path must be URL-encoded. Error handling is included for common connection and JSON decoding issues."},"warnings":[{"fix":"Migrate to `requests-unixsocket2` by installing it and updating import statements (if not already using `from requests_unixsocket import ...`).","message":"The original `requests-unixsocket` library is considered abandoned and is incompatible with recent versions of `requests` and `urllib3`. `requests-unixsocket2` was created to address these compatibility issues and is the recommended alternative.","severity":"breaking","affected_versions":"<1.0.0 (for requests-unixsocket)"},{"fix":"Use `session = requests_unixsocket.Session()` and then `session.get(...)` or call `requests_unixsocket.monkeypatch()` at the start of your application.","message":"Direct calls to `requests.get()`, `requests.post()`, etc., will not utilize UNIX domain sockets by default. You must either instantiate `requests_unixsocket.Session()` and use its methods, or call `requests_unixsocket.monkeypatch()` to globally enable UNIX socket support for `requests` functions.","severity":"gotcha","affected_versions":"All versions of requests-unixsocket2"},{"fix":"Ensure your deployment environment is Linux if using abstract namespace sockets, or use file-based UNIX domain sockets for broader compatibility.","message":"Abstract namespace sockets (e.g., URLs like `http+unix://\\0test_socket/path`) are a Linux-specific feature. Code using abstract namespace sockets will not work on other operating systems.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}