---
name: python-urllib-socks5-proxyhandler-gotcha
description: "Python urllib.request.ProxyHandler не умеет по-настоящему SOCKS5 — тихо рвёт соединение на строгих SOCKS5-листенерах вроде sing-box, хотя строка вида \"socks5://host:port\" выглядит правильно"
metadata: 
  node_type: memory
  type: project
  originSessionId: 6f344612-b945-4107-b457-8ad2163cd988
  modified: 2026-08-04T10:42:21.897Z
---

`urllib.request.ProxyHandler({"https": "socks5://host:port"})` в Python
**не является настоящей SOCKS5-поддержкой** — модуль понимает только
HTTP-proxy-семантику (CONNECT-туннель). Строка `socks5://` не парсится
специально, и итоговый запрос на самом деле бьёт по адресу как по
HTTP/HTTPS-прокси.

**Симптом:** через один локальный SOCKS5-прокси на mini (например `xray`,
который у нас дуально терпит и HTTP-CONNECT-синтаксис на том же порту)
код "работает". Через другой, строго стандартный SOCKS5-only листенер
(например `sing-box`) — тот же код падает со `Connection reset by peer`
на КАЖДОМ запросе. Выглядит как проблема сети/прокси, а на деле — баг
клиентской библиотеки.

**Диагностика:** воспроизвести тот же запрос через `curl --socks5
host:port ...` — если curl проходит чисто, а Python-код рвётся, дело
именно в urllib, не в прокси/сети.

**Фикс:** если у прокси-демона есть отдельный HTTP-proxy инпут (у
sing-box hy2-client на mini это `:2092` рядом с SOCKS5 на `:2091`,
см. `~/Services/singbox-hy2-client/config.json`) — переключить
`urllib.request.ProxyHandler` на `http://host:2092` вместо
`socks5://host:2091`. Тот же исходящий IP, но протокол клиенту нативно
понятен. Альтернатива — переписать код на `httpx`/`PySocks` с явной
SOCKS5-поддержкой, но обычно проще воспользоваться готовым HTTP-инпутом,
если прокси-демон его уже поднимает.

Найдено и починено на [[gemini-web2api]] (анонимный/cookie-based доступ
к Gemini на mini, порт :1717) — see investpilot Decisions.md D54 для
полного разбора инцидента (IP-гейт Google + этот баг вместе давали
100%-ный отказ). Актуально для ЛЮБОГО Python-сервиса на mini, который
конфигурирует прокси строкой `socks5://` через голый `urllib`.
