Install & Compatibility
Where this runs
tested against v1.7.1.20260518 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.029s · 17.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.029s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
socks
✓ import socks
✗ from types_pysocks import socks
Types-pysocks provides type hints for the 'socks' module, not a runtime module itself. You should import 'socks' from the actual PySocks library.
set_default_proxy
✓ import socks
socks.set_default_proxy(...)
Access functions and classes directly from the 'socks' module after import.
This quickstart demonstrates how to configure PySocks to route `urllib.request` traffic through a SOCKS5 proxy. It first sets a global default proxy and then 'monkey-patches' the standard `socket.socket` to use PySocks' `socksocket`, ensuring all subsequent socket operations (like those by `urllib.request`) go through the proxy. Ensure you have a running SOCKS proxy at the specified address and port.
import socks
import socket
import urllib.request
import os
# --- Configuration for SOCKS proxy ---
# Replace with your proxy details
PROXY_TYPE = socks.SOCKS5 # or socks.SOCKS4, socks.HTTP
PROXY_ADDR = os.environ.get('SOCKS_PROXY_ADDR', '127.0.0.1')
PROXY_PORT = int(os.environ.get('SOCKS_PROXY_PORT', 9050))
PROXY_USERNAME = os.environ.get('SOCKS_PROXY_USER', '')
PROXY_PASSWORD = os.environ.get('SOCKS_PROXY_PASS', '')
# Set up the default proxy for all subsequent socket connections
if PROXY_USERNAME and PROXY_PASSWORD:
socks.set_default_proxy(PROXY_TYPE, PROXY_ADDR, PROXY_PORT, True, PROXY_USERNAME, PROXY_PASSWORD)
else:
socks.set_default_proxy(PROXY_TYPE, PROXY_ADDR, PROXY_PORT)
# "Monkey-patch" the socket module to use PySocks
socket.socket = socks.socksocket
try:
# Make a request that will now go through the SOCKS proxy
print(f"Attempting to fetch external IP via proxy {PROXY_ADDR}:{PROXY_PORT}...")
with urllib.request.urlopen('http://icanhazip.com') as response:
external_ip = response.read().decode('utf-8').strip()
print(f"External IP (via proxy): {external_ip}")
except socks.ProxyError as e:
print(f"Failed to connect via proxy: {e}")
except urllib.error.URLError as e:
print(f"URL Error: {e.reason}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaPySocks' `socks.set_default_proxy` globally monkey-patches `socket.socket`. While convenient, this can have unintended side effects on other parts of your application or libraries that also interact with the socket module directly. Consider using `requests` with its `proxies` argument for HTTP/HTTPS traffic, which uses PySocks internally in a less intrusive way, or manually creating `socks.socksocket` instances for fine-grained control.fixFor HTTP/HTTPS traffic, use the `requests` library with its `proxies` dictionary (e.g., `proxies={'http': 'socks5://user:pass@host:port'}`). For other protocols, explicitly create and use `socks.socksocket` instances rather than global monkey-patching where possible. affects: All versions of PySocks
gotchaPySocks' native HTTP proxy support is limited to proxies that use CONNECT tunneling. For standard HTTP proxies, it is generally recommended to use the HTTP client's native proxy support (e.g., `requests`' `proxies` parameter or `urllib.request.ProxyHandler`).fixIf connecting to an HTTP proxy that does not support CONNECT tunneling, use your HTTP client's built-in proxy configuration. For `requests`, this means using the `proxies` argument (e.g., `proxies={'http': 'http://user:pass@host:port'}`). affects: All versions of PySocks
gotchaWhen using `requests` with a SOCKS proxy, you might encounter issues with DNS resolution if the proxy URL uses `socks5://`. By default, `requests` may attempt local DNS resolution.fixTo ensure remote DNS resolution (i.e., DNS resolution by the proxy server), use `socks5h://` in your proxy URL. Example: `proxies = {'http': 'socks5h://127.0.0.1:9050', 'https': 'socks5h://127.0.0.1:9050'}`. affects: All versions of PySocks when used with `requests`
gotchaPySocks has limited support for IPv6. Attempting to use IPv6 addresses might lead to errors or unexpected behavior.fixPrefer IPv4 proxy addresses and target hosts when using PySocks. If IPv6 is essential, consider alternative proxy libraries or methods that explicitly support it.
affects: All versions of PySocks
Upgrade
Version history
1.7.1.20260518latest on PyPI · released May 18, 2026
Audit
Dependencies
pysocksrequiredProvides the runtime functionality for which these stubs offer type hints.