#Что происходит и когда возникает ошибка
На ARM (например, aarch64, arm64) pip может не находить готовый wheel, хотя пакет существует для x86_64. Если исходники доступны, сборка возможна не всегда: это зависит от языка, системных библиотек, Python и поддержки архитектуры.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Автор не публикует ARM wheelГотовый двоичный файл собран только для иной архитектуры. | На странице релиза есть x86_64, но нет aarch64/arm64 | Поискать поддерживаемую версию или исходную сборку. |
| Текущий Python несовместимТег python/abi колеса не совпадает. | Есть ARM wheel для другой версии/ABI Python | Подобрать поддерживаемую версию Python. |
| Сборка требует ARM-библиотекиИсходный код зависит от нативных инструментов и библиотек. | При сборке заголовки, Rust или compiler error | Подготовить точные сборочные зависимости по документации. |
#Подробная диагностика и исправление
- Определите архитектуру и версию PythonВ терминале целевого ARM-устройства выполните проверку. Linux часто выводит
aarch64, macOS Apple Silicon —arm64; это сведения о машине, а не гарантия, что установленный Python той же архитектуры. Для самого Python используйтеplatform.machine().Linux · Терминал (Bash)КомандаПодходит для всех ОС; не требует администратора.python -c "import platform,sys; print(platform.machine()); print(sys.version); print(sys.executable)"
- Проверьте совместимые теги wheelКоманда
python -m pip debug --verboseпоказывает совместимые теги установленного Python. Сопоставьте их с именами архивов wheel в проверенном выпуске библиотеки: нужны совпадающие платформа, ABI и версия интерпретатора.Linux · Терминал (Bash)КомандаДиагностика; представление вывода не является стабильным программным интерфейсом.python -m pip debug --verbose
- Проверьте наличие только двоичного выпускаВ свежем venv попробуйте установку с
--only-binary=:all:. Если получаетеNo matching distribution found, это означает отсутствие подходящего кандидата в выбранном индексе при действующих ограничениях, а не отсутствие проекта как такового. - В тестовом venv; установка при наличии wheelLinux · Терминал (Bash)С осторожностьюВ тестовом venv; установка при наличии wheel. Системные пакеты не трогать.
python -m pip install --only-binary=:all: ИМЯ_ПАКЕТАКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- Найдите официально поддерживаемую комбинациюОткройте документацию и страницу выпусков проекта, проверьте поддержку ARM, минимальную версию Python и требования внешних библиотек. Для Apple Silicon не используйте wheel от Linux aarch64; для Windows ARM64 — не выбирайте пакет от macOS arm64.
- Если сборка из исходников поддерживается, подготовьте инструментыНа тестовом ARM-хосте изучите ошибку первой команды сборки. Может потребоваться компилятор, Rust, система сборки и заголовки специальных библиотек. Установку ОС-зависимых инструментов согласуйте с администратором и выполняйте по инструкции конкретного пакета, а не универсальным набором команд.
- Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюВ новом venv и каталоге проекта; собирает wheel с зависимостями, возможна долгая компиляция.
python -m pip wheel --wheel-dir ./built-wheels ИМЯ_ПАКЕТАКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- После сборки проверьте импорт и работуЕсли wheel собран, установите из локального каталога в новое окружение. Запустите функциональный пример; успешное создание wheel не гарантирует, что программа сможет загрузить все системные библиотеки. Если не получается, используйте официальный поддерживаемый вариант без самостоятельного исправления двоичных файлов.
- Избегайте неподходящих бинарных файловНе переименовывайте имя x86_64 wheel в arm64 и не копируйте библиотеки другой архитектуры в системные папки: они не станут совместимыми. Если проект официально не поддерживает ARM, зафиксируйте ограничение и рассмотрите замену зависимости.
#Проверка результата и действия при неуспехе
Есть подходящий ARM wheel или подтверждённая сборка из исходников, пакет импортируется и выполняет тест на целевом устройстве.
Если исправление не помогло, вернитесь к точному сообщению об ошибке, сохраните версию Python, адрес целевого окружения и очищенный от секретов журнал; выясните, на каком шаге результат отличается от ожидаемого. Не изменяйте глобальный Python ради устранения сбоя проекта.