解决 Missing dependencies for SOCKS

Missing dependencies for SOCKS support 的意思是：Requests 拿到了一个 SOCKS 代理 URL（例如 socks5:// 或 socks5h://），却无法在当前运行的 Python 中执行 import socks，也就是导入 PySocks 安装的那个模块。Requests 在建立任何连接之前就抛出这个错误，所以此时还没有访问过代理。

代理 URL 不一定写在你的代码里：Requests 也会从环境中的 ALL_PROXY 或 all_proxy 读取它。而 pip 运行在自带的一份 Requests 副本上，所以只要设置了这个变量，pip install pysocks 也会以同样的信息中止。

下面的结果记录于 2026 年 10 月 5 日，使用 Requests 2.34.2、HTTPX 0.28.1、pip 26.2.1、PySocks 1.7.1 和 socksio 1.0.0，运行在 Python 3.13.5 和 3.14.4 上，每个用例都使用全新的虚拟环境。两个 Python 版本的结果相同。

方法 1：把 PySocks 装进运行你代码的那个 Python

python -m pip install "requests[socks]"

这个附加依赖（extra）只增加一个包 PySocks，它可导入的模块名是 socks。直接按名字安装 pysocks 也可以。请写 python -m pip，不要只写 pip：前者会安装到 python 命令启动的那个解释器里，而单独的 pip 可能属于另一个环境。在实验中，当 PATH 上的 pip 指向第二个虚拟环境时，pip install "requests[socks]" 打印了 Successfully installed PySocks-1.7.1，脚本却仍然抛出同样的错误。

检查正在运行的解释器：

python -c "import socks, sys; print(sys.executable, socks.__file__)"

它会打印解释器路径，以及 import socks 实际解析到的文件，后者应该是该解释器 site-packages 里的 socks.py。ModuleNotFoundError: No module named 'socks' 说明这个 Python 里没有 PySocks。

方法 2：你并没有设置代理

不传 proxies 时，Requests 会根据环境变量来构造代理配置。它的文档列出了 http_proxy、https_proxy、no_proxy 和 all_proxy，以及它们的大写形式。列出你的进程继承了哪些变量：

env | grep -i _proxy

在实验中，一个代码里没有任何代理设置的脚本，只设置 ALL_PROXY=socks5://127.0.0.1:1080 时抛出了这个错误，只设置小写的 all_proxy 时也一样。HTTP_PROXY 里放 socks5:// URL 的结果相同。Requests issue #3516 就是这种情况：报告者的环境里有 all_proxy，代码在升级到 Requests 2.11 后出错，一位维护者说对 all_proxy 的支持正是从这个版本开始的。

如果你需要这个 SOCKS 代理，使用方法 1。如果不需要，就在设置它的地方把变量去掉，例如 shell 配置文件或容器镜像。实验中的四个细节：

• 空值等同于未设置。ALL_PROXY= 得到的是直连请求和状态码 200。
• 小写优先。设置了 all_proxy 而把 ALL_PROXY 清空时，错误仍然存在。清空 all_proxy 则消除了错误，即使 ALL_PROXY 仍然有值。两个都要清空。
• ALL_PROXY 只是后备。同时把 HTTP_PROXY 设为一个 HTTP 代理时，对 http:// URL 的请求去连了那个代理，完全没有走到 SOCKS 代码。
• 代码可以选择不读环境。session.trust_env = False 在 ALL_PROXY 仍然有值时返回了 200，把目标主机加入 NO_PROXY 也一样。

代理环境变量列出了每个客户端读取哪些变量，Python Requests 代理指南讲解了 trust_env。

方法 3：pip 也报 Missing dependencies for SOCKS support

pip 通过一份内置（vendored）的 Requests 下载，并读取同样的变量。在全新的虚拟环境中，把 all_proxy 或 ALL_PROXY 设为 SOCKS URL：

$ python -m pip install "requests[socks]"
WARNING: There was an error checking the latest version of pip.
ERROR: Could not install packages due to an OSError: Missing dependencies for SOCKS support.

pip download 和 pip index versions 则以一段 traceback 结束，最后一行是 pip._vendor.requests.exceptions.InvalidSchema: Missing dependencies for SOCKS support. 只为这一条命令清空这些变量：

ALL_PROXY= all_proxy= python -m pip install "requests[socks]"

在命令前加 env -u ALL_PROXY -u all_proxy 同样有效。只清空 ALL_PROXY 不行，因为 all_proxy 仍然有值。

然后再决定这个变量是否应该继续保持导出。安装 PySocks 之后，Requests 使用了 ALL_PROXY 里的代理，并通过实验用的 SOCKS 服务器返回了 200。pip 则不然：pip 26.2.1 以 TypeError: PoolKey.__new__() got an unexpected keyword argument 'key_proxy_ssl_context' 中止，而 pip 25.1.1 通过同一个代理装上了包。使用 pip 26.2.1 时，请继续为 pip 命令清空该变量，或者只给需要代理的程序设置代理。

方法 4：AttributeError: module 'socks' has no attribute 'PROXY_TYPE_SOCKS5'

这时 import socks 找到了东西，但不是 PySocks。Python 先搜索脚本所在目录，对 python -c 和 python -m 则是当前目录，最后才加入 site-packages，所以你自己名为 socks 的文件或文件夹会胜出。方法 1 里的检查命令能显示实际导入的是什么：

给这个文件或文件夹改名。在最后一行里，一个名为 socks 的普通文件夹把缺少依赖的错误变成了 AttributeError，所以改名之后仍然需要方法 1。

HTTPX: Using SOCKS proxy, but the 'socksio' package is not installed

HTTPX 有自己的 SOCKS 依赖。缺少它时，HTTPX 0.28.1 抛出：

ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.

python -m pip install "httpx[socks]"

这条命令安装了 socksio 1.0.0，同一个请求随后通过代理返回了 200。其余方法同样适用：

• 无论是在代码里写 proxy="socks5://..."，还是环境中只有 ALL_PROXY 或 all_proxy，都会出现这个错误。它在创建客户端时抛出：设置了 ALL_PROXY 时，不带参数的 httpx.Client() 在发出任何请求之前就失败了。
• 空的 ALL_PROXY 和 trust_env=False 各自得到了直连的 200。
• 这两个库不能互相替代。只安装了 PySocks 的 HTTPX 仍然抛出 ImportError，只安装了 socksio 的 Requests 仍然抛出 InvalidSchema。

要检查导入，把方法 1 那条命令里的 socks 换成 socksio。HTTPX 异步代理指南里有完整的客户端配置。

能导入之后：有意识地选择 socks5:// 或 socks5h://

这时出现别的错误反而是进展：安装了 PySocks 而代理端口上没有任何监听时，Requests 抛出带 Connection refused 的 ConnectionError，这属于网络问题。

下一个要决定的是协议写法。在 Requests 中，socks5:// 在你的机器上解析主机名，socks5h:// 把主机名发给代理；HTTPX 两种写法都发送主机名。socks5 与 socks5h：六个客户端实际发给代理的是什么记录了每个客户端的实测结果；如果你还在选择协议，可以看 HTTP 与 SOCKS5 代理。

测试方法

在 Ubuntu 26.04.1 上，一切都在 127.0.0.1：以 python -m http.server 作为目标，另有一个小型 SOCKS5 中继，记录它收到的每个请求。47 个用例中的每一个都在两个 Python 版本上运行，使用全新的虚拟环境、不含无关文件的工作目录和空的主目录，除该用例指明的变量外没有任何代理变量。没有使用代理账号；唯一的出站流量是 pip 访问 PyPI。在所有失败的用例中，中继都没有记录到连接。

实验压缩包包含运行脚本、SOCKS5 中继、README 和记录的结果。

未测试：macOS 和 Windows、SOCKS4 和需要认证的 SOCKS 代理、旧版本的 Requests 和 HTTPX，以及 pip 以外的安装工具。

ipvolt 是一项面向开发者的代理服务，目前尚未开放；加入早期访问名单，开放时你会收到一封邮件。