#Что происходит и когда возникает ошибка
Установка большого пакета надолго останавливается на Downloading, ReadTimeoutError или повторяет попытки. Нужно различать медленное соединение, отсутствие свободного места, ограничения зеркала и долгую распаковку или сборку.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Плохое соединение или нестабильное зеркалоСервер либо сеть прерывает передачу больших файлов. | Счётчик загрузки не увеличивается, в логе Retry/ReadTimeout | Проверить источник и соединение, скорректировать таймаут. |
| Мало места на дискеpip использует кэш и временный каталог при скачивании и распаковке. | В журнале No space left on device | Освободить место в своих каталогах, не удаляя системные данные. |
| Пакет уже не скачивается, а собираетсяВремя тратится на компиляцию или разрешение зависимостей. | На экране Building wheel или установка build dependencies | Смотреть подробный вывод и совместимые колёса. |
#Подробная диагностика и исправление
- Уточните этап, на котором всё останавливаетсяВ терминале прочитайте последнюю строку.
Downloadingозначает сетевой этап,Installing build dependencies— подготовку сборки,Building wheel— компиляцию,Resolving— подбор версий. Если процесс медленно работает, но вывод меняется, не называйте его зависшим только по отсутствию шкалы.
- Проверьте сеть и доступ к выбранному индексуВ браузере откройте страницу официального индекса или корпоративного зеркала; при служебном прокси уточните его параметры у администратора. В том же терминале проверьте активный URL индекса через конфигурацию. Не переключайте корпоративный проект на публичный индекс без разрешения.
- Чтение настроек, без прав администратораLinux · Терминал (Bash)КомандаЧтение настроек, без прав администратора. Перед пересылкой вывода удалите токены в URL.
python -m pip config list
- Попробуйте контролируемое скачивание отдельноВ отдельной тестовой папке выполните
pip download -d ./wheels ИМЯ_ПАКЕТА. Эта команда собирает файлы для установки, но не изменяет рабочую среду. Папка должна пополняться скачанными файлами. При ошибке зафиксируйте на каком файле она возникла. - В каталоге проекта; создаёт подкаталог wheels и скачивает зависимостиLinux · Терминал (Bash)КомандаВ каталоге проекта; создаёт подкаталог wheels и скачивает зависимости. Нужны место и доступ к сети.
python -m pip download -d ./wheels ИМЯ_ПАКЕТА
- Измените таймаут лишь при подтверждённой медленной сетиЕсли журнал показывает повторные
Read timed out, проверьте, помогает ли увеличенный таймаут 120 секунд на стабильном и доверенном индексе.--retries 3ограничивает число повторов; параметры не исправят отказ сервера, подмену сертификата или обрыв VPN. - Запускайте в отдельном каталоге, без прав администратора; не используйте --trusted-hostLinux · Терминал (Bash)КомандаЗапускайте в отдельном каталоге, без прав администратора; не используйте --trusted-host.
python -m pip download --timeout 120 --retries 3 -d ./wheels ИМЯ_ПАКЕТА
- Проверьте свободное место и кэшПосмотрите свободный объём на системном разделе и разделе временных файлов средствами ОС. Команда
python -m pip cache dirпоказывает место хранения кэша;python -m pip cache info— его объём. Не очищайте весь кэш на общем сервере без согласования.Linux · Терминал (Bash)КомандаКоманды только читают сведения. Доступность зависит от версии pip.python -m pip cache dirpython -m pip cache info
- Используйте готовый wheel при долгой сборкеЕсли задержка на
Building wheel, проверьте наличие двоичного выпуска для вашей ОС и Python с--only-binary=:all:в чистой среде. При его отсутствии прочтите требования сборки. Не прерывайте установку, которая изменяет рабочее окружение, без предварительной резервной копии.
- Подтвердите успешную установкуПосле завершения вызовите
python -m pip show ИМЯ_ПАКЕТА, затем запустите минимальный пример проекта. Если медленная загрузка повторяется на всех пакетах, приложите очищенный от секретов журнал и данные о сети администратору.
#Проверка результата и действия при неуспехе
Загрузка завершается без сетевых повторов, пакет появляется в целевом окружении и импортируется. Если скачивание работает, а сборка нет, дальнейшая диагностика относится к компиляции.
Если исправление не помогло, вернитесь к точному сообщению об ошибке, сохраните версию Python, адрес целевого окружения и очищенный от секретов журнал; выясните, на каком шаге результат отличается от ожидаемого. Не изменяйте глобальный Python ради устранения сбоя проекта.