Install & Compatibility
Where this runs
tested against v3.0.0 · 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.925 runs
installs and imports cleanly · install 0.0s · import 0.105s · 24.2MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.8s · import 0.097s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Proxy (sync)
✓ from python_socks.sync import Proxy
Proxy (asyncio)
✓ from python_socks.async_.asyncio import Proxy
This quickstart demonstrates how to establish a synchronous connection through a SOCKS5 proxy to fetch the IP address from `check-host.net`. The proxy URL is retrieved from the `PYTHON_SOCKS_PROXY_URL` environment variable for secure credential handling. It includes SSL/TLS wrapping for HTTPS connections.
import ssl
import os
from python_socks.sync import Proxy
# Get proxy URL from environment variable, e.g., "socks5://user:password@127.0.0.1:1080"
proxy_url = os.environ.get('PYTHON_SOCKS_PROXY_URL', 'socks5://127.0.0.1:1080')
try:
proxy = Proxy.from_url(proxy_url)
# `connect` returns standard Python socket in blocking mode
sock = proxy.connect(dest_host='check-host.net', dest_port=443)
# Wrap socket for SSL/TLS if connecting to HTTPS
sock = ssl.create_default_context().wrap_socket(
sock=sock,
server_hostname='check-host.net'
)
request = (
b'GET /ip HTTP/1.1\r\n'
b'Host: check-host.net\r\n'
b'Connection: close\r\n\r\n'
)
sock.sendall(request)
response_parts = []
while True:
data = sock.recv(4096)
if not data:
break
response_parts.append(data)
full_response = b"".join(response_parts)
print("Received response through proxy:")
print(full_response.decode('utf-8', errors='ignore'))
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure a SOCKS proxy is running and PYTHON_SOCKS_PROXY_URL environment variable is set correctly.")
print("Example: export PYTHON_SOCKS_PROXY_URL=\"socks5://user:pass@127.0.0.1:1080\"")
finally:
if 'sock' in locals() and sock:
sock.close()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'socks.asyncio'
The asynchronous module for `python-socks` is `socks_asyncio`, not a submodule of `socks`.
fixUse `import socks_asyncio` instead of `from socks import asyncio` or similar attempts to import from `socks.asyncio`.
socks.ProxyConnectionError: Could not connect to proxy 127.0.0.1:9050: Connection refused
The `python-socks` client failed to establish a connection with the specified proxy server, likely because the proxy is offline or rejecting connections.
fixVerify the proxy server's address and port, ensure the proxy service is running and accessible from your machine, and check firewall settings.
socks.ProxyAuthenticationError: Authentication failed
The proxy server requires authentication, and the provided username or password by `python-socks` was incorrect or missing.
fixEnsure the correct username and password are provided when initializing the proxy connection, e.g., `socks.SOCKS5_PROXY('host', port, username='user', password='pwd')`. socks.ProxyError: SOCKS5 proxy handshake failed: invalid server response
The client attempted a SOCKS5 handshake with a proxy server that does not support SOCKS5, or the proxy server returned an unexpected and invalid response during the handshake, often due to a misconfigured proxy type.
fixVerify the actual type of proxy server (SOCKS4, SOCKS5, HTTP CONNECT) and ensure you are using the corresponding `socks.SOCKS4_PROXY`, `socks.SOCKS5_PROXY`, or `socks.HTTP_PROXY` constant.
RuntimeWarning: coroutine 'create_connection' was never awaited
An asynchronous function (`create_connection` from `socks_asyncio` or similar) was called within an `async def` function but its result (a coroutine object) was not awaited, meaning its execution was never triggered.
fixEnsure that all calls to asynchronous functions are prefixed with the `await` keyword, e.g., `await socks_asyncio.create_connection(...)`.
Upgrade
Version history
3.0.0latest on PyPI · released Aug 11, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.8 or higher.
async-timeoutoptionalOptional, required for asyncio backend >= 4.0.
triooptionalOptional, required for trio backend >= 0.24.
curiooptionalOptional, required for curio backend >= 1.4.
anyiooptionalOptional, required for anyio backend >= 3.3.4.