Updated and actively maintained version of SocksiPy, with bug fixes and extra features.

Acts as a drop-in replacement to the socket module.

• SOCKS proxy client for Python 2.6 - 3.x
• TCP and UDP both supported
• HTTP proxy client included but not supported or recommended (you should use urllib2's or requests' own HTTP proxy interface)
• urllib2 handler included. pip install / setup.py install will automatically install the sockshandler module.

pip install PySocks

Or download the tarball / git clone and...

python setup.py install

These will install both the socks and sockshandler modules.

Alternatively, include just socks.py in your project.

Warning: PySocks/SocksiPy only supports HTTP proxies that use CONNECT tunneling. Certain HTTP proxies may not work with this library. If you wish to use HTTP (not SOCKS) proxies, it is recommended that you rely on your HTTP client's native proxy support (proxies dict for requests, or urllib2.ProxyHandler for urllib2) instead.

import socks

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

s.set_proxy(socks.SOCKS5, "localhost") # SOCKS4 and SOCKS5 use port 1080 by default
# Or
s.set_proxy(socks.SOCKS4, "localhost", 4444)
# Or
s.set_proxy(socks.HTTP, "5.5.5.5", 8888)

# Can be treated identical to a regular socket object
s.connect(("www.somesite.com", 80))
s.sendall("GET / HTTP/1.1 ...")
print s.recv(4096)

To monkeypatch the entire standard library with a single default proxy:

import urllib2
import socket
import socks

socks.set_default_proxy(socks.SOCKS5, "localhost")
socket.socket = socks.socksocket

urllib2.urlopen("https://www.somesite.com/") # All requests will pass through the SOCKS proxy

Note that monkeypatching may not work for all standard modules or for all third party modules, and generally isn't recommended. Monkeypatching is usually an anti-pattern in Python.

Example use case with the sockshandler urllib2 handler. Note that you must import both socks and sockshandler, as the handler is its own module separate from PySocks. The module is included in the PyPI package.

import urllib2
import socks
from sockshandler import SocksiPyHandler

opener = urllib2.build_opener(SocksiPyHandler(socks.PROXY_TYPE_SOCKS5, "127.0.0.1", 9050))
print opener.open("https://www.somesite.com/") # All requests made by the opener will pass through the SOCKS proxy

Original SocksiPy README attached below, amended to reflect API changes.

SocksiPy

A Python SOCKS module.

(C) 2006 Dan-Haim. All rights reserved.

See LICENSE file for details.

WHAT IS A SOCKS PROXY?

A SOCKS proxy is a proxy server at the TCP level. In other words, it acts as a tunnel, relaying all traffic going through it without modifying it. SOCKS proxies can be used to relay traffic using any network protocol that uses TCP.

WHAT IS SOCKSIPY?

This Python module allows you to create TCP connections through a SOCKS proxy without any special effort. It also supports relaying UDP packets with a SOCKS5 proxy.

PROXY COMPATIBILITY

SocksiPy is compatible with three different types of proxies:

1. SOCKS Version 4 (SOCKS4), including the SOCKS4a extension.
2. SOCKS Version 5 (SOCKS5).
3. HTTP Proxies which support tunneling using the CONNECT method.

SYSTEM REQUIREMENTS

Being written in Python, SocksiPy can run on any platform that has a Python interpreter and TCP/IP support. This module has been tested with Python 2.3 and should work with greater versions just as well.

Simply copy the file "socks.py" to your Python's lib/site-packages directory, and you're ready to go. [Editor's note: it is better to use python setup.py install for PySocks]

F