Install & Compatibility
Where this runs
tested against v1.7.1 · 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.032s · 21.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.0s · import 0.027s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
socks
✓ import socks
The primary module for SOCKS client functionality.
socksocket
✓ import socks
socket.socket = socks.socksocket
Used for monkey-patching the standard socket module to route all traffic through the proxy.
set_default_proxy
✓ import socks
socks.set_default_proxy(socks.SOCKS5, 'localhost', 9050)
Sets a global default proxy for all subsequent socket connections.
This example demonstrates how to configure PySocks to route all outgoing `socket` traffic through a SOCKS proxy by monkey-patching the standard `socket.socket`. It attempts to fetch the external IP address using `urllib.request` which will then use the proxified socket. Proxy details are loaded from environment variables for flexibility.
import socks
import socket
import os
from urllib.request import urlopen
# Configure proxy details from environment variables or use defaults
proxy_type = socks.SOCKS5
proxy_addr = os.environ.get('SOCKS_PROXY_HOST', '127.0.0.1')
proxy_port = int(os.environ.get('SOCKS_PROXY_PORT', 9050))
try:
# Set a default SOCKS proxy for all socket connections
socks.set_default_proxy(proxy_type, proxy_addr, proxy_port)
# Monkeypatch the standard socket module to use PySocks
socket.socket = socks.socksocket
print(f"Attempting to connect via SOCKS{proxy_type} proxy at {proxy_addr}:{proxy_port}")
# Make a request using urllib, which now uses the proxified socket
with 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"Proxy connection failed: {e}. Check proxy settings and availability.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaPySocks' built-in HTTP proxy support is limited to HTTP proxies that use CONNECT tunneling. For general HTTP proxying, it is highly recommended to use the native proxy support of your HTTP client library (e.g., the `proxies` argument in `requests`) instead of PySocks' direct HTTP proxy option.fixFor HTTP proxies, use your HTTP client's native proxy configuration (e.g., `requests.get(url, proxies={'http': 'http://proxy.example.com:8080'})`). PySocks is primarily designed for SOCKS proxies. affects: All versions
gotchaMonkey-patching the standard library's `socket` module (e.g., `socket.socket = socks.socksocket`) can be a powerful way to globally route traffic, but it is generally considered an anti-pattern in Python. It might lead to unexpected behavior with other modules or libraries that make assumptions about the standard socket.fixPrefer using `requests` with its `proxies` argument (which internally uses PySocks if `requests[socks]` is installed) for HTTP/HTTPS traffic. For direct socket control, use `socks.socksocket()` instances explicitly instead of monkey-patching.
affects: All versions
gotchaWhen configuring SOCKS proxies, especially with the `requests` library, use the `socks5h://` scheme (e.g., `socks5h://proxyhost:port`) instead of `socks5://`. The 'h' ensures that DNS resolution is performed remotely by the proxy server, preventing potential DNS leaks that could reveal your real IP address.fixAlways use `socks5h://` in your proxy URLs for SOCKS5 proxies to ensure remote DNS resolution, which is crucial for anonymity and privacy.
affects: All versions
gotchaReports and discussions suggest that the PySocks project has seen limited activity and new releases in recent years, leading some to consider it 'in very bad shape' or a 'discontinued project'. While still functional and widely used (especially as a `requests` dependency), this might indicate slower bug fixes or new feature development.fixFor new projects, evaluate alternatives like `python-socks` if long-term active maintenance is a critical factor. For existing projects, be aware of the maintenance status and consider community patches or forks if needed.
affects: Versions >= 1.7.0
breakingPySocks does not inherently support IPv6 connections. Attempts to connect to IPv6 addresses (either directly or through a proxy that resolves to an IPv6 address) will result in an `urlopen error PySocks doesn't support IPv6`.fixIf IPv6 support is required, consider using an alternative SOCKS library that provides IPv6 compatibility (e.g., `python-socks`) or ensure all your network interactions and proxy servers are configured to use IPv4 addresses.
affects: All versions
breakingPySocks does not inherently support IPv6. Attempts to connect to or through proxies that resolve to IPv6 addresses, or connect to IPv6 destination addresses, will result in connection errors indicating a lack of IPv6 support.fixIf IPv6 support is required, consider using alternatives like `python-socks` which offers IPv6 compatibility. If you must use PySocks, ensure that all proxy and destination addresses are exclusively IPv4, or configure your system/network to prefer IPv4 when resolving hostnames.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'socks'
The `pysocks` library, which is imported as `socks`, has not been installed in the current Python environment.
requests.exceptions.ProxyError: SOCKS5Error: 0x05
The SOCKS proxy server refused the connection, indicating it might be down, unreachable, or incorrectly configured in the `requests` proxy settings.
fixVerify the proxy server address and port, ensure the proxy service is running and accessible from your environment, and check firewall settings.
socks.GeneralProxyError: Could not connect to proxy server
The `pysocks` library failed to establish a TCP connection to the specified SOCKS proxy server, often due to an incorrect address, port, or network issues.
fixDouble-check the proxy host and port configured with `socks.set_default_proxy()` (or `socks.setdefaultproxy()`) and ensure the proxy server is running and reachable.
TypeError: an integer is required (got type str)
The `port` argument passed to `socks.setdefaultproxy()` or `socks.set_default_proxy()` was provided as a string instead of an integer.
fixConvert the port number to an integer before passing it to the function, for example: `socks.set_default_proxy(socks.SOCKS5, "localhost", int("9050"))`. Upgrade
Version history
1.7.1latest on PyPI · released Sep 20, 2019
Audit
Dependencies
No dependency data recorded yet.