pip timeout, retries и resume-retries: настройка сети

Три параметра решают разные сетевые проблемы

В актуальной справке pip `--timeout <sec>` задаёт socket timeout и по умолчанию равен 15 секундам. `--retries <retries>` задаёт максимум попыток установить новое HTTP-соединение после проблем и имеет default 5, а `--resume-retries <resume_retries>` — максимум попыток продолжить или перезапустить незавершённую загрузку, также default 5. Эти опции нельзя считать тремя названиями одной настройки. Если ошибка — `CERTIFICATE_VERIFY_FAILED`, увеличение timeout не исправит цепочку доверия. Если private index отвечает 401/403, повторные соединения не исправят токен или права. Поэтому сначала классифицируйте ошибку по тексту, а уже затем меняйте сетевую политику.

Совет: Сохраните один полный лог неудачной установки до изменения настроек. По нему легче отличить timeout от TLS, DNS, 401/403 и ошибки самого package build.

Что менять при разных симптомах

• Симптом | С чего начать
• Read timed out на медленном канале | Умеренно увеличить --timeout и проверить скорость/прокси.
• Временные разрывы соединения | Проверить --retries; не увеличивать бесконечно, если ошибка стабильная.
• Большой wheel обрывается ближе к концу | Проверить поддержку и значение --resume-retries.
• CERTIFICATE_VERIFY_FAILED | Не трогать timeout; исправлять CA/TLS.
• 401/403 от private index | Проверять URL, токен и права, а не сетевые повторы.
• Name or service not known/DNS | Исправлять DNS/network path; retries только маскирует повторяемую причину.

Предупреждение: Увеличение timeout не делает сервер быстрее. Оно лишь разрешает pip дольше ждать, поэтому слишком большое значение заметно растягивает каждый реальный сетевой сбой.

Безопасная диагностика и настройка

1. 1. Повторите установку с обычными настройками и запишите точную ошибку, URL index и этап, на котором она возникает.
2. 2. Проверьте, открывается ли тот же index из среды CI/container и нет ли proxy, VPN или DNS-различий.
3. 3. Если ошибка действительно timeout, попробуйте ограниченное изменение, например `pip install --timeout 60 <package>`.
4. 4. При временных connection errors задайте разумное число `--retries`, сохраняя общий предел времени job.
5. 5. Для обрыва больших загрузок отдельно рассмотрите `--resume-retries`, не подменяя им обычные retries.
6. 6. Когда рабочее значение найдено, перенесите стабильный параметр в `pip config` или environment (`PIP_TIMEOUT` и соответствующие переменные), если он нужен всей среде.
7. 7. Перезапустите чистую job и измерьте время. Если build просто стал ждать в десять раз дольше и всё равно падает, вернитесь к диагностике сети.

Важно: Для CI добавляйте ещё и внешний job timeout. Он защищает pipeline, если комбинация большого timeout и множества retries превращает одну установку в час ожидания.

Команда, environment и config: где лучше хранить значения

pip поддерживает несколько уровней конфигурации. Для разового теста удобнее CLI: видно, что именно вы меняете. Для конкретного runner можно использовать environment — документация приводит `PIP_TIMEOUT=60` как эквивалент `--timeout=60`. Для стабильной настройки машины или пользователя подходит `pip config`, но важно помнить приоритеты: command line перекрывает environment, а environment — config files. Это объясняет частую загадку, когда вы записали timeout в config, но CI продолжает использовать другое значение из `PIP_TIMEOUT`. Проверяйте активную конфигурацию через `pip config debug` и не размазывайте одну опцию по трём уровням без необходимости. Чем меньше скрытых override, тем легче воспроизводить сетевую проблему.

Чего не делать при нестабильном pip install

• Не ставить timeout в сотни или тысячи секунд до понимания причины.
• Не увеличивать retries при постоянной 401/403, TLS или DNS-ошибке — это не временный сетевой сбой.
• Не добавлять `--trusted-host` только ради того, чтобы убрать certificate error.
• Не полагаться на cache как доказательство исправления: чистая job может снова обратиться к сети.
• Не держать разные timeout в CLI, PIP_TIMEOUT и pip.conf без документации приоритетов.
• Не забывать ограничение времени всей CI-job, даже если pip умеет повторять запросы.

Как понять, что настройка действительно помогла

Успех — это не один случайный зелёный запуск. Проверьте несколько чистых job в той же сети и убедитесь, что время установки стало предсказуемым, а количество повторов не скрывает постоянную деградацию index. Если пакет загружается стабильно только при timeout 300 секунд, измерьте latency до registry и скорость передачи: возможно, зеркало перегружено или proxy буферизует трафик. Для private index полезно сравнить установку небольшого и большого wheel. Не меняйте одновременно timeout, retries, proxy и registry — иначе невозможно понять, что именно сработало. Рабочая конфигурация должна быть минимальной: один понятный параметр на конкретную проблему, лог с причиной и разумный верхний предел времени pipeline.

Если ломается только один большой пакет

Сравните размер wheel и источник файла. Большой бинарный wheel сильнее показывает проблемы канала, чем небольшой metadata request, поэтому общий `pip index` может казаться доступным, а загрузка всё равно обрывается. Если отказ происходит примерно в одной и той же точке, проверьте ограничения proxy, дискового места и промежуточного cache. Стабильная точка сбоя обычно говорит о постоянной причине, а не о случайной потере пакетов. В таком случае увеличение retries лишь повторяет тот же сценарий и удлиняет диагностику. Для воспроизводимости записывайте не только итоговые числа, но и причину их выбора. Например, timeout 60 секунд может быть оправдан спутниковым каналом или медленным корпоративным proxy, тогда как retries 10 без объяснения через полгода выглядит случайной магией. Если сеть улучшилась, параметры следует пересмотреть: слишком щедрые ожидания продолжают скрывать регрессии. Метрики длительности `pip install` в CI дают простой сигнал, что проблема вернулась ещё до полного падения pipeline.

Что учитывать

Условия меняются. Страница отражает состояние на 2026-09-21; при расхождении с официальной документацией приоритет у первоисточника.

Источники и проверка

Инструкция составлена редакцией N1RO на 2026-09-21. Перед действием сверьте актуальные условия на официальном сайте сервиса или производителя.

• pip general options (v26.2.1)
• pip Configuration (v26.2.1)