PySocks

1.7.1 verified Tue May 12 auth: no python install: verified quickstart: verified

PySocks is a Python SOCKS client module that enables applications to route their network traffic through SOCKS proxy servers. It acts as a robust, modern fork of SocksiPy, offering a drop-in replacement for Python's standard `socket` module with added proxy functionalities. It is also a key underlying dependency for SOCKS proxy support in the popular `requests` library.

pip install pysocks

Common errors

error ModuleNotFoundError: No module named 'socks' ↓

cause The `pysocks` library, which is imported as `socks`, has not been installed in the current Python environment.

fix

pip install pysocks

error requests.exceptions.ProxyError: SOCKS5Error: 0x05 ↓

cause The SOCKS proxy server refused the connection, indicating it might be down, unreachable, or incorrectly configured in the `requests` proxy settings.

fix

Verify the proxy server address and port, ensure the proxy service is running and accessible from your environment, and check firewall settings.

error socks.GeneralProxyError: Could not connect to proxy server ↓

cause 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.

fix

Double-check the proxy host and port configured with socks.set_default_proxy() (or socks.setdefaultproxy()) and ensure the proxy server is running and reachable.

error TypeError: an integer is required (got type str) ↓

cause The `port` argument passed to `socks.setdefaultproxy()` or `socks.set_default_proxy()` was provided as a string instead of an integer.

fix

Convert the port number to an integer before passing it to the function, for example: socks.set_default_proxy(socks.SOCKS5, "localhost", int("9050")).

Warnings

gotcha PySocks' 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. ↓

fix For 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.

gotcha Monkey-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. ↓

fix Prefer 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.

gotcha When 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. ↓

fix Always use `socks5h://` in your proxy URLs for SOCKS5 proxies to ensure remote DNS resolution, which is crucial for anonymity and privacy.

gotcha Reports 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. ↓

fix For 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.

breaking PySocks 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`. ↓

fix If 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.

breaking PySocks 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. ↓

fix If 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.

Install

pip install requests[socks]

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) pysocks - - 0.02s 17.9M

3.10 alpine (musl) socks - - 0.03s 21.2M

3.10 slim (glibc) pysocks - - 0.01s 18M

3.10 slim (glibc) socks - - 0.01s 22M

3.11 alpine (musl) pysocks - - 0.04s 19.7M

3.11 alpine (musl) socks - - 0.07s 23.3M

3.11 slim (glibc) pysocks - - 0.04s 20M

3.11 slim (glibc) socks - - 0.04s 24M

3.12 alpine (musl) pysocks - - 0.07s 11.6M

3.12 alpine (musl) socks - - 0.04s 15.1M

3.12 slim (glibc) pysocks - - 0.05s 12M

3.12 slim (glibc) socks - - 0.04s 16M

3.13 alpine (musl) pysocks - - 0.04s 11.2M

3.13 alpine (musl) socks - - 0.03s 14.7M

3.13 slim (glibc) pysocks - - 0.04s 12M

3.13 slim (glibc) socks - - 0.03s 15M

3.9 alpine (musl) pysocks - - 0.03s 17.4M

3.9 alpine (musl) socks - - 0.02s 20.5M

3.9 slim (glibc) pysocks - - 0.02s 18M

3.9 slim (glibc) socks - - 0.02s 21M

Imports

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.

Quickstart verified last tested: 2026-04-23

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}")