Geonode logo
Library and script errors

How to Fix Missing Dependencies for SOCKS Support in Python

Find which client and setting asked for SOCKS, then add the matching package to the Python that runs it.

Updated

Get residential proxiesCheck your proxy

TL;DR

Missing dependencies for SOCKS support is the InvalidSchema error Python requests raises when a proxy URL starts with socks but PySocks is not installed, so nothing has reached the proxy yet. The fastest fix is python -m pip install "requests[socks]" with the interpreter that runs your script.

What the error looks like in each client

The last line of each traceback on macOS; urllib3's wording depends on your Python version.

WhereWhat you see
Python requests 2.26 to 2.34 (socks4, socks5 or socks5h proxy)requests.exceptions.InvalidSchema: Missing dependencies for SOCKS support.
pip 24.0 and 26.1 (last traceback line after ERROR: Exception:)pip._vendor.requests.exceptions.InvalidSchema: Missing dependencies for SOCKS support.
urllib3 1.26 or 2.x ProxyManager on Python 3.9 to 3.12urllib3.exceptions.ProxySchemeUnknown: Proxy URL had unsupported scheme socks5, should use http:// or https://
urllib3 1.26 or 2.x ProxyManager on Python 3.14urllib3.exceptions.ProxySchemeUnknown: Not supported URL scheme Proxy URL had unsupported scheme socks5, should use http:// or https://
urllib3.contrib.socks import (warning before No module named 'socks')DependencyWarning: SOCKS support in urllib3 requires the installation of optional dependencies: specifically, PySocks.
httpx 0.27 and 0.28 (socks5 proxy, socksio missing)ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.
zsh 5.9 (brackets not quoted)zsh: no matches found: requests[socks]

Why this happens

Out of the box, requests cannot talk to SOCKS proxies at all.

On first import it looks for an optional module; when that is absent, a stub takes its place and raises this error for every proxy URL whose scheme begins with socks, from code or an environment variable.

Diagnose your SOCKS dependency error first

These checks separate a missing package from the wrong environment, a stray variable or another client.

  • Read the exception name on the traceback's last line; InvalidSchema means requests, an ImportError naming socksio means httpx, ProxySchemeUnknown means urllib3.

  • Run python -c "import socks" with the interpreter behind your script; ModuleNotFoundError confirms the add-on is absent there.

  • Compare your script's sys.executable with the path python -m pip --version prints; different paths mean pip installed into another Python.

  • Search your code for socks; if nothing matches, run env | grep -i proxy, because a socks URL in ALL_PROXY or HTTPS_PROXY reaches requests too.

  • If the error survives a successful install inside a notebook or a running worker, that process still holds the requests it imported earlier.

Solutions ranked by effectiveness

Work down the cards: the missing module, then a stray variable, then urllib3 code that needs a SOCKS manager.

  1. Most common fix

    Install the SOCKS extra for this Python

    Applies when the import check fails. Add the extra through the very interpreter that runs the code, then start the process again.

    1. Run python -m pip install "requests[socks]"; for httpx the extra is "httpx[socks]".

    2. In Jupyter, use the %pip magic instead, then restart the kernel.

  2. Check next

    Remove a stray SOCKS proxy variable

    Applies when your code names no SOCKS proxy, or pip fails the same way; the socks URL then comes from an environment variable.

    1. Unset the variable holding the socks URL, such as ALL_PROXY, and drop its export line.

    2. Or pass pip --proxy http://USERNAME:PASSWORD@proxy.geonode.io:9000; it outranks ALL_PROXY.

  3. For developers

    Use SOCKSProxyManager in urllib3 code

    Applies to scripts written for urllib3. Build a SOCKSProxyManager from the socks URL; where a library creates its proxy manager for you, give it an http:// proxy instead.

    # pip install "urllib3[socks]"
from urllib3.contrib.socks import SOCKSProxyManager

proxy = "socks5h://USERNAME:PASSWORD@proxy.geonode.io:11000"
http = SOCKSProxyManager(proxy)
r = http.request("GET", "https://example.com/", timeout=30)
print(r.status)

Stop the SOCKS dependency error from coming back

Habits that keep the SOCKS package wherever the code runs and keep SOCKS URLs out of shared settings.

  1. Make CI import the socks module, so an image built without the add-on fails before release.

  2. If you pin PySocks yourself, avoid 1.5.7; the requests[socks] extra excludes exactly that release.

  3. Upgrade httpx to 0.28 or later before writing socks5h URLs; 0.27 rejects that scheme as unknown.

  4. Write python -m pip in Dockerfiles and setup scripts, so each package lands in the interpreter that will import it.

Confirm traffic leaves through the proxyGeonode's verification guide compares your IP before and after you switch the proxy on.
Try residential proxies

Related errors

Learn more

FAQ

It means requests got a socks proxy URL but cannot load PySocks in that Python, so the call stopped on your machine. Nothing was sent, so neither the proxy nor your login is at fault.

Its vendored requests cannot load SOCKS support, so a socks URL from --proxy, pip.conf or ALL_PROXY ends the run with ERROR: Exception. Adding PySocks to pip's environment, fetched over an HTTP proxy or none, enables it.

With socks5 your machine looks up the site's address and hands the proxy an IP; with socks5h the proxy resolves the name. requests and urllib3 accept both, matching curl's meaning of the two schemes.

Yes, SOCKS5 only, and only once socksio is present; otherwise creating a client raises ImportError. A socks4 URL fails with ValueError: Unknown scheme for proxy URL.

urllib3's ProxyManager and proxy_from_url accept only http:// and https:// proxy URLs and raise ProxySchemeUnknown for anything else. Libraries that pass your proxy straight to proxy_from_url, such as botocore, show it for a socks URL.

zsh treats the square brackets as a file name pattern and stops because no file matches, so pip never starts. Put the argument in quotes, "requests[socks]", which works the same in bash.

Rotating or sticky over SOCKS5

Geonode's SOCKS5 ports 11000-11010 rotate per request; 12000-12010 keep one IP for a set time.

Try residential proxies