PySocks Documentation

You can force the entire Python standard library (and many third-party modules) to use a specific proxy by setting a default proxy and overriding the global socket.socket class.

Warning: Monkeypatching is generally considered an anti-pattern in Python and may not work for all modules.

import socket
import socks

# Set the default proxy for new socksockets
socks.set_default_proxy(socks.SOCKS5, "localhost")

# Override the standard socket class
socket.socket = socks.socksocket

For proxying HTTP traffic, it is highly recommended to use the requests library. requests uses PySocks internally to handle SOCKS proxies. Avoid using PySocks' own HTTP proxy implementation as it only supports CONNECT-based proxies and is not recommended.

import requests

requests.get(url, proxies={
    "http": "socks5://proxyhostname:9050", 
    "https": "socks5://proxyhostname:9050"
})

You can install PySocks using pip or by installing from source. This will install both the socks and sockshandler modules.

Alternatively, you can simply include the socks.py file directly in your project.

pip install pysocks

To install PySocks, it is recommended to use the standard Python installation command:

python setup.py install

The socks.socksocket class provides an API identical to the standard library's socket.socket. You can configure a proxy for any socksocket instance using the set_proxy() method.

Supported proxy types include:

• socks.SOCKS5 (defaults to port 1080 if not specified)
• socks.SOCKS4 (defaults to port 1080 if not specified)
• socks.HTTP (supports CONNECT-based HTTP proxies)

import socks

s = socks.socksocket() # Same API as socket.socket in the standard lib

# Configure SOCKS5 on localhost (default port 1080)
s.set_proxy(socks.SOCKS5, "localhost") 

# Or configure SOCKS4 on localhost with a specific port
s.set_proxy(socks.SOCKS4, "localhost", 4444)

# Or configure an HTTP proxy
s.set_proxy(socks.HTTP, "5.5.5.5", 8888)

# Use it like a regular socket
s.connect(("www.somesite.com", 80))
s.sendall("GET / HTTP/1.1 ...")
print(s.recv(4096))

The socks.socksocket class is the core of the module. It is derived from the standard socket class and can be used to create TCP connections through a SOCKS4, SOCKS5, or HTTP proxy.

To use it, initialize the object (ideally without parameters), configure the proxy using set_proxy(), and then call connect() as you would with a normal socket.