#Что происходит и когда возникает ошибка
Сообщение Failed building wheel или Could not build wheels for ... возникает при сборке пакета из исходников. Причину нужно искать выше в журнале: компилятор, системные заголовки, сборочные зависимости или неподдерживаемый Python.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Нет готового совместимого wheelДля версии Python или платформы опубликован только исходный архив. | pip загружает .tar.gz, а не .whl | Проверить доступные двоичные сборки. |
| Отсутствует компилятор или библиотекаНужно окружение сборки, которого нет на компьютере. | В журнале gcc: command not found, cl.exe или fatal error: ...h | Установить требуемые инструменты по инструкции пакета. |
| Сбой build backendСборочное средство несовместимо с версией Python либо пакетом. | В стеке упомянуты pyproject.toml, setuptools, meson или Rust | Изучить первую ошибку сборки, проверить поддерживаемые версии. |
#Подробная диагностика и исправление
- Сохраните полный журнал установкиВ терминале отдельного тестового окружения повторите команду с
-v, записав вывод в файл только при отсутствии секретов в параметрах. Прокрутите выше последней строкиsubprocess-exited-with-error: именно там часто написано название отсутствующего файла, команды компилятора или версия, с которой не совместим пакет. - Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюВ .venv под обычным пользователем; устанавливает пакет при успехе, предварительно сохраните список версий.
python -m pip install -v ИМЯ_ПАКЕТАКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- Проверьте наличие двоичного пакета без компиляцииСоздайте отдельную пустую среду и выполните установку с
--only-binary=:all:. Если кандидат найден, pip установит готовый wheel. Если получаетеNo matching distribution found, подходящего wheel для этих ограничений/индекса нет — это не доказательство, что пакета вообще нет. - Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюОтдельная .venv; опция запрещает сборку из исходников; результат зависит от версии Python, ОС и настроенного индекса.
python -m pip install --only-binary=:all: ИМЯ_ПАКЕТАКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- Сопоставьте совместимость Python и архитектурыВыполните
python -Vиpython -m pip debug --verbose, посмотрите совместимые теги в разделеCompatible tags:. Сравните их с окончанием имени wheel на странице официального проекта. Теги CPython, версии и архитектуры должны совпадать.Linux · Терминал (Bash)КомандаКоманда от обычного пользователя; формат pip debug может меняться.python -Vpython -m pip debug --verbose
- Если исходники неизбежны, установите точную сборочную зависимостьНайдите в документации именно этого пакета требования для вашей ОС. На Debian/Ubuntu иногда нужны gcc и python3-dev; для других пакетов — Rust, CMake, OpenSSL или библиотеки базы. Установку системных пакетов согласуйте с администратором; не выполняйте случайные команды из чужих журналов.
- Проверьте альтернативную поддерживаемую версиюЕсли проект не публикует wheel для новой версии Python, подготовьте тестовое окружение с поддерживаемой версией Python или подходящим выпуском библиотеки. Не понижайте Python, используемый системными службами, и не выбирайте версию наугад; сверяйте метаданные Requires-Python.
- Подтвердите, что сборка не маскирует новый сбойПосле успешной установки выполните
python -m pip check, затем импорт и минимальный тест библиотеки из её документации. Ошибка импорта динамической библиотеки после успешной сборки требует отдельной проверки ABI и системных зависимостей.
#Проверка результата и действия при неуспехе
Пакет появился в pip show, pip check не сообщает конфликтов, пример использования выполняется без ошибки импорта/сборки.
Если исправление не помогло, вернитесь к точному сообщению об ошибке, сохраните версию Python, адрес целевого окружения и очищенный от секретов журнал; выясните, на каком шаге результат отличается от ожидаемого. Не изменяйте глобальный Python ради устранения сбоя проекта.