modulenotfounderror: no module named 'socks': install PySocks (or the requests[socks] extra)

TL;DR

modulenotfounderror: no module named 'socks' means the PySocks package is missing: the module you import is called socks, but the distribution you install is called PySocks, and pip cannot bridge that gap from the import statement. Run pip install PySocks (or pip install "requests[socks]" if you use requests), then verify with python -c "import socks". SOCKS support is an optional extra in requests and urllib3, so it is never installed by default.

ModuleNotFoundError: No module named 'socks'

Use this when

• The traceback goes through urllib3.contrib.socks or a requests SOCKS proxy call
• You are routing requests or urllib3 through a SOCKS5 proxy
• The error appears in a Docker image or CI runner that your local machine does not reproduce

Not for this skill when

• The import works but the proxy connection or authentication fails: that is a proxy configuration problem, not a missing package
• You only use HTTP proxies: those need no extra package
• The missing module name is different (bs4, nacl, tokenizers): same shape, different distribution; see Related skills

Steps

1. Install the distribution that provides the socks module:

pip install PySocks

or, if you are using requests with SOCKS proxies, install the extra so the version stays compatible:

pip install "requests[socks]"

Expected: pip reports PySocks installed (the requests extra pins a compatible PySocks for you).

2. Verify the import in the same interpreter that raised the error:

python -c "import socks; print('ok')"

Expected: ok. If it still fails, you installed into a different environment than the one running the code; check which python and which pip (python -m pip is the reliable pairing).

3. Pin it so the error does not come back. Add PySocks (or requests[socks]) to requirements.txt, your pyproject dependencies, or your Dockerfile install step.

Expected: a fresh environment built from those files imports socks with no error.

Variant phrasings

no module named socks

The same error without the ModuleNotFoundError prefix, as pasted from a traceback tail. Same fix: pip install PySocks.

urllib3 socks proxy import error

urllib3's SOCKS support lives in urllib3.contrib.socks and imports the same socks module, so the traceback may name urllib3 instead of your code. The missing package is still PySocks.

works locally, fails in docker

Your local environment has PySocks (often pulled in by something else); the image does not. Step 3 is the durable fix: declare the dependency in the image build.

Root cause

SOCKS support is optional in both requests and urllib3, so the dependency is not installed by default. The module kept the short socks name while the distribution took the Py-prefixed name, so installing what the error literally names (pip install socks) targets the wrong thing; PySocks is the distribution that provides the module.

Edge cases

• pip install socks installs an unrelated package and does not fix the import; uninstall it and install PySocks.
• Virtualenv and conda mixes: run python -m pip install PySocks so the package lands in the interpreter that runs your code.
• SOCKS5 with remote DNS (socks5h in requests) still needs PySocks; the h only changes where DNS resolves.

Tool compatibility

PySocks 1.7+ with requests 2.x and urllib3 1.x and 2.x on Python 3. The requests[socks] extra pins a compatible PySocks.

Related skills

• ModuleNotFoundError: No module named 'tokenizers': https://vectle.com/skills/skl_j4GrDEsYFfVy5Oh3CwMY3A
• ModuleNotFoundError: No module named 'nacl': https://vectle.com/skills/skl_BZhM7odjxyOfLPg7sJziSA
• Unable to import module 'main': No module named 'boto3': https://vectle.com/skills/skl_evmyrWS8QeYRAe2y5mVmAw

Provenance

Built from the PySocks project page and the requests SOCKS documentation, linked in the evidence.