python-socks

What it is and what it does

python-socks is a low-level proxy client library that handles the protocol details of connecting through SOCKS4, SOCKS4a, SOCKS5, and HTTP CONNECT proxies. It returns standard Python sockets (or async equivalents) that you can then use with your own networking code or higher-level libraries. The package is designed to be used internally by higher-level HTTP client wrappers, but can also be used directly when you need fine-grained control over proxy connections.

The library offers three API styles: synchronous blocking sockets, and asynchronous support for asyncio, trio, and anyio frameworks. It supports proxy chaining (routing through multiple proxies in sequence) and works across macOS, Windows, and Linux. Since it has no required runtime dependencies, installation is straightforward, and you can opt into async support by installing extras only when needed.

Use it for:

• Route HTTP/HTTPS requests through a SOCKS5 proxy in a synchronous application by wrapping the returned socket with ssl and sending raw HTTP requests.
• Build an async HTTP client that tunnels connections through multiple chained proxies using asyncio or trio event loops.
• Establish encrypted connections to remote hosts via an HTTP CONNECT proxy for scenarios where SOCKS is unavailable.
• Test network applications against different proxy types (SOCKS4, SOCKS5, HTTP CONNECT) without modifying application code.
• Integrate proxy support into socket-based HTTP libraries by subclassing connection classes to use proxy.connect().

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides SOCKS4(a), SOCKS5(h), and HTTP CONNECT proxy client functionality with both synchronous and asynchronous (asyncio, trio, anyio) APIs for Python.

Yes. The package is actively maintained, has zero known vulnerabilities, supports Python >= 3.9, and carries a permissive Apache-2.0 license. Low install friction and no required dependencies make adoption straightforward. Install it if you need direct control over proxy connections or are building a library that wraps proxy functionality.

Install

python-socks on PyPI

pip install python-socks

uv add python-socks

poetry add python-socks

Installing python-socks

Before you install

Low install friction with no runtime dependencies in the base package. Actively maintained with a recent release and steady repository activity. Supports Python >= 3.9.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions, making it suitable for most production environments.

Quickstart

pip install python-socks

from python_socks.sync import Proxy

proxy = Proxy.from_url("socks5://user:password@127.0.0.1:1080")
sock = proxy.connect(dest_host="example.com", dest_port=443)

Requires Python >= 3.9. Optional async support requires installing extras: python-socks[asyncio], python-socks[trio], or python-socks[anyio].

Verify before relying

• Whether optional dependencies (async-timeout >= 5.0, trio >= 0.30, anyio >= 4.12) are automatically installed with extras or require manual specification.
• Performance characteristics or throughput limits when handling concurrent proxy connections.
• Whether proxy authentication supports all SOCKS5 authentication methods or only username/password.

Package facts

Evidence: python_socks-3.0.0-py3-none-any.whl

Keywords: socks, socks5, socks4, http, proxy, asyncio, trio, anyio

Tags

More WWW/HTTP packages