# 解决 Missing dependencies for SOCKS

Source: https://ipvolt.com/zh/guides/fix-missing-dependencies-for-socks-support
Markdown: https://ipvolt.com/zh/guides/fix-missing-dependencies-for-socks-support.md
Language: zh-CN

[ipvolt 首页](https://ipvolt.com/zh.md) / [指南](https://ipvolt.com/zh/guides.md) / 解决 Missing dependencies for SOCKS

故障排查
发布于: 2026-10-05
阅读约 7 分钟
作者： ipvolt

Python Requests、pip 或 HTTPX 报 Missing dependencies for SOCKS support？安装 requests[socks]，或清除 ALL_PROXY 环境变量。

`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` 也会以同样的信息中止。

| 你看到的 | 原因 | 解决方法 |
| --- | --- | --- |
| `requests.exceptions.InvalidSchema: Missing dependencies for SOCKS support.`，而且你的代码设置了 SOCKS 代理 | 这个 Python 无法导入 PySocks | 方法 1：`python -m pip install "requests[socks]"` |
| 同样的错误，但你的代码没有设置代理 | `ALL_PROXY` 或其他代理变量里是一个 SOCKS URL | 方法 2：移除该变量，或安装 PySocks |
| `ERROR: Could not install packages due to an OSError: Missing dependencies for SOCKS support.` | pip 读取了同一个变量 | 方法 3：只为这一条命令清空它 |
| `AttributeError: module 'socks' has no attribute 'PROXY_TYPE_SOCKS5'` | 被导入的是你自己的 `socks.py` 或 `socks/` 包，而不是 PySocks | 方法 4：给它改名 |
| `ImportError: Using SOCKS proxy, but the 'socksio' package is not installed.` | HTTPX 需要的是 socksio，不是 PySocks | `python -m pip install "httpx[socks]"` |

下面的结果记录于 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

```sh
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`，脚本却仍然抛出同样的错误。

检查正在运行的解释器：

```sh
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 会根据环境变量来构造代理配置。它的[文档](https://requests.readthedocs.io/en/latest/user/advanced/#proxies)列出了 `http_proxy`、`https_proxy`、`no_proxy` 和 `all_proxy`，以及它们的大写形式。列出你的进程继承了哪些变量：

```sh
env | grep -i _proxy
```

在实验中，一个代码里没有任何代理设置的脚本，只设置 `ALL_PROXY=socks5://127.0.0.1:1080` 时抛出了这个错误，只设置小写的 `all_proxy` 时也一样。`HTTP_PROXY` 里放 `socks5://` URL 的结果相同。[Requests issue #3516](https://github.com/psf/requests/issues/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` 也一样。

[代理环境变量](/zh/guides/proxy-environment-variables)列出了每个客户端读取哪些变量，[Python Requests 代理指南](/zh/guides/python-requests-proxy)讲解了 `trust_env`。

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

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

```text
$ 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.` 只为这一条命令清空这些变量：

```sh
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 [先搜索脚本所在目录](https://docs.python.org/3/library/sys_path_init.html)，对 `python -c` 和 `python -m` 则是当前目录，最后才加入 `site-packages`，所以你自己名为 `socks` 的文件或文件夹会胜出。方法 1 里的检查命令能显示实际导入的是什么：

| Python 最先搜索的目录里有 | 已安装 PySocks | 结果 | 检查命令打印 |
| --- | --- | --- | --- |
| `socks.py` | 是 | `AttributeError` | 你的 `socks.py` |
| 带 `__init__.py` 的 `socks/` | 是 | `AttributeError` | 你的 `socks/__init__.py` |
| 不带 `__init__.py` 的 `socks/` | 是 | 正常，状态码 200 | `site-packages` 里的 PySocks |
| 不带 `__init__.py` 的 `socks/` | 否 | `AttributeError`，而不是 `InvalidSchema` | `None` |

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

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

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

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

```sh
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 异步代理指南](/zh/guides/httpx-async-proxy)里有完整的客户端配置。

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

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

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

## 测试方法

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

[实验压缩包](https://ipvolt.com/downloads/fix-missing-dependencies-for-socks-support/socks-missing-dependencies-lab.zip)包含[运行脚本](https://ipvolt.com/downloads/fix-missing-dependencies-for-socks-support/run_lab.py)、[SOCKS5 中继](https://ipvolt.com/downloads/fix-missing-dependencies-for-socks-support/socks5_relay.py)、[README](https://ipvolt.com/downloads/fix-missing-dependencies-for-socks-support/README.md) 和[记录的结果](https://ipvolt.com/downloads/fix-missing-dependencies-for-socks-support/results.json)。

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

ipvolt 是一项面向开发者的代理服务，目前尚未开放；[加入早期访问名单](https://ipvolt.com/#waitlist-closing)，开放时你会收到一封邮件。

## 参考来源与延伸阅读

- [Requests: SOCKS proxies and the requests[socks] extra](https://requests.readthedocs.io/en/latest/user/advanced/#socks)
- [Requests: proxies and the proxy environment variables](https://requests.readthedocs.io/en/latest/user/advanced/#proxies)
- [psf/requests issue #3516: Missing dependencies for SOCKS support](https://github.com/psf/requests/issues/3516)
- [HTTPX: proxies and SOCKS](https://www.python-httpx.org/advanced/proxies/)
- [HTTPX: environment variables](https://www.python-httpx.org/environment_variables/)
- [PySocks on PyPI](https://pypi.org/project/PySocks/)
- [Python: how the sys.path module search path is initialized](https://docs.python.org/3/library/sys_path_init.html)

## 相关指南

- [代理环境变量：HTTP_PROXY 与 NO_PROXY](https://ipvolt.com/zh/guides/proxy-environment-variables.md)
- [Python Requests 代理配置：认证与 SOCKS5](https://ipvolt.com/zh/guides/python-requests-proxy.md)
- [HTTPX 异步代理：配置与 PoolTimeout 诊断](https://ipvolt.com/zh/guides/httpx-async-proxy.md)

## 关于 ipvolt

示例使用通用的代理设置，并附上原始技术文档链接。具体产品的行为请向你的服务商确认。ipvolt 仍在开发中。

[阅读英文原文](https://ipvolt.com/guides/fix-missing-dependencies-for-socks-support.md)

## 了解何时开放体验。

ipvolt · 开发中

我们正在为开发者和数据团队打造代理基础设施。加入意向名单，ipvolt 就绪时第一时间收到通知。

开放体验时仅发一封通知邮件，不发送其他邮件。

[申请抢先体验](https://ipvolt.com/zh/guides/fix-missing-dependencies-for-socks-support#waitlist-closing)

[隐私政策](https://ipvolt.com/privacy)