DevOps / CI/CD

Docker-образ на Apple Silicon не запускается: как исправить в 2026 году

Docker-образ на Apple Silicon не запускается: как исправить в 2026 году

no matching manifest for linux/arm64 или контейнер сразу завершается после запуска — это не одна и та же проблема.

Сначала проверьте, есть ли у образа вариант linux/arm64. Для долгосрочной работы выбирайте нативный arm64 или multi-platform-образ; запуск amd64 через эмуляцию оставляйте для временной диагностики. Если в лаборатории нет Mac, изолированную проверку можно провести на удалённом Apple Silicon Mac, а уже затем решать вопрос о покупке оборудования.

Эта статья предназначена для трёх групп:

  • исследователей и аспирантов, которые воспроизводят контейнеризированный научный проект на Apple Silicon;
  • разработчиков научного ПО, поддерживающих образы для amd64 и arm64;
  • руководителей лабораторий, которым нужно принять или передать macOS-ориентированный контейнерный процесс без собственного Mac.

Архитектура образа и фактическая причина сбоя

Фраза «образ скачался» ещё не означает, что программа внутри него совместима с компьютером. В цепочке участвуют как минимум три уровня:

  • macOS-хост с процессором Apple Silicon;
  • Linux-виртуальная машина, внутри которой работает Docker Desktop;
  • платформа образа и архитектура бинарных файлов внутри контейнера.

Поэтому Docker-образ Apple Silicon может загрузиться, но завершиться с ошибкой уже на этапе запуска бинарного файла. Обратная ситуация тоже встречается: образ объявлен как linux/amd64, Docker предлагает эмуляцию, но конкретная научная библиотека падает при выполнении инструкции или загрузке динамической зависимости.

Для первичной проверки используйте:

docker buildx imagetools inspect IMAGE:TAG

или:

docker manifest inspect IMAGE:TAG

Официальная документация Docker показывает, как проверять манифест и дочерние платформы образа через docker manifest inspect. Для более подробного просмотра платформ, слоёв и метаданных подходит docker buildx imagetools inspect.

Ищите в результате:

linux/arm64
linux/amd64

Если присутствует только linux/amd64, образ не является нативным для Apple Silicon. Если есть обе платформы, Docker обычно выбирает подходящий вариант автоматически, но это ещё не доказывает идентичность научного результата.

Что обнаружено Что это означает Приоритетное действие
Только linux/arm64 Образ рассчитан на ARM-среду Запускать нативно, затем проверить зависимости
Только linux/amd64 Нативного варианта для Apple Silicon нет Временно проверить эмуляцию или собрать ARM-вариант
linux/arm64 и linux/amd64 Опубликован multi-platform-образ Проверить выбранный digest и содержимое обеих сборок
Платформа есть, но бинарник не запускается Ошибка может быть внутри образа Исследовать бинарные файлы и динамические библиотеки
Образ не имеет корректного манифеста Docker не может выбрать платформу Исправить публикацию или сборочный pipeline

Почему Docker-образ не запускается на Mac с M-серией из-за несовпадения архитектуры? Чаще всего registry не содержит подходящего linux/arm64 варианта, либо внутри внешне совместимого образа находится бинарный файл только для amd64. Сам факт успешного pull проверяет доступность слоёв, а не работоспособность каждой программы.

Эмуляция amd64 против нативного arm64

Параметр платформы помогает проверить гипотезу:

docker run --platform linux/amd64 IMAGE:TAG

При сборке аналогичный режим выглядит так:

docker buildx build \
  --platform linux/amd64 \
  -t research-test:amd64 .

Это не превращает amd64-образ в нативный ARM-образ. Docker Desktop запускает Linux-контейнер внутри виртуализированной среды, а Intel-бинарные файлы проходят через дополнительный слой преобразования. Apple описывает запуск Intel Linux-бинарников как отдельный механизм с ограничениями, а Docker прямо предупреждает, что эмуляция не равна нативному исполнению. Подробности приведены в документации Apple о преобразовании Intel-бинарников в Linux-виртуальных машинах.

Симптомы нужно разделять, а не объединять в одну ошибку:

  • Контейнер завершается сразу. Проверьте docker logs CONTAINER_ID, код завершения и команду ENTRYPOINT.
  • Появляется Illegal instruction. Вероятен несовместимый бинарник, инструкция процессора или библиотека, а не только неверный тег платформы.
  • Файловый watcher не реагирует. Проблема может быть связана с границей между файловой системой macOS и Linux-виртуальной машиной.
  • Запуск проходит, но расчёт ведёт себя нестабильно. Сравните библиотечные версии, потоки, внешние инструменты и итоговые файлы.
  • Ресурсы расходуются непропорционально. Эмуляция добавляет накладные расходы, поэтому время выполнения нельзя автоматически переносить на нативный Linux или ARM.

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

Эмуляция оправдана для короткой проверки: выяснить, запускается ли интерфейс, прочитать трассировку, локализовать место падения или временно проверить чужой образ. Для публикационной воспроизводимости, регулярного pipeline и длительных вычислений приоритет должен быть у нативного образа либо у заранее проверенной отдельной среды amd64.

Зависимости внутри контейнера

Иногда Docker-образ запускается, но научное ПО не устанавливается. В этом случае проблема уже не в выборе платформы при старте.

Разделяйте сообщения по типу:

  • менеджер пакетов не находит версию — возможно, отсутствует репозиторий для нужной архитектуры или базовый образ слишком старый;
  • исходный код не компилируется — проверьте компилятор, системные заголовки и поддерживаемую архитектуру;
  • динамическая библиотека не загружается — найдите её через ldd, file или аналогичный инструмент внутри контейнера;
  • пакет устанавливается, но импорт завершается ошибкой — проверьте заранее собранные wheel-пакеты, системные библиотеки и ABI;
  • внешний научный инструмент запускается с ошибкой — определите архитектуру самого исполняемого файла, а не только Python- или R-окружения.

Полезный набор проверок:

uname -m
dpkg --print-architecture
file /path/to/program
ldd /path/to/program
python -c "import platform; print(platform.machine())"

Команды должны выполняться внутри контейнера. Значение arm64 на хосте не доказывает, что программа в контейнере собрана под ARM. Аналогично, наличие Python-пакета в индексе не гарантирует, что его нативное расширение поддерживает нужную платформу.

Рекомендуемый порядок исправления:

  • заменить базовый образ на официальный multi-platform-вариант;
  • проверить системные пакеты для arm64;
  • собрать проблемную библиотеку из исходного кода, если проект это поддерживает;
  • заменить зависимость на версию с опубликованным ARM-пакетом;
  • только после этого рассматривать запуск всего контейнера через linux/amd64.

Установка всех зависимостей заново не является универсальным решением. Если в Dockerfile жёстко указан архив для x86_64, пакетный менеджер не сможет исправить это автоматически.

Dockerfile и кросс-платформенная сборка

При проблеме Docker Buildx нужно проверить не только команду запуска, но и сам процесс сборки. В Dockerfile часто встречаются скрытые ограничения:

FROM --platform=linux/amd64 base-image

или:

RUN curl -L https://example.invalid/tool-amd64.tar.gz | tar -xz

Первый пример принудительно выбирает платформу базового образа. Второй загружает файл, который может не работать в ARM-среде. В реальном проекте такие строки нужно искать также в shell-скриптах, Makefile, CI-конфигурации и файлах установки научных инструментов.

Для multi-platform-сборки используется команда:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example/project:latest \
  --push .

Флаг --push здесь важен для публикации manifest list в registry. Полное описание параметров находится в справочнике docker buildx build, а общая модель multi-platform-сборок разобрана в официальном руководстве Docker.

В многоэтапной сборке полезно различать:

  • BUILDPLATFORM — среда, где выполняется этап сборки;
  • TARGETPLATFORM — платформа итогового образа;
  • TARGETARCH — архитектурная часть целевой платформы;
  • BUILDARCH — архитектура сборочной среды.

Docker описывает эти переменные в отдельной документации по переменным сборки. Они помогают передавать правильные параметры компилятору, но не исправляют исходный код, сторонний бинарник или пакет без ARM-поддержки.

Пример диагностического Dockerfile:

# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM compiler-image AS build
ARG TARGETOS
ARG TARGETARCH

WORKDIR /src
COPY . .

RUN echo "building for ${TARGETOS}/${TARGETARCH}" \
    && ./build.sh

FROM runtime-image
COPY --from=build /src/bin/app /usr/local/bin/app
ENTRYPOINT ["/usr/local/bin/app"]

Такой шаблон лишь показывает разделение сборочной и целевой платформ. Для каждого проекта нужно проверить, умеет ли компилятор создавать целевой бинарник и доступен ли runtime-образ для обеих архитектур.

Вариант сборки Когда подходит Главный риск
Нативная сборка linux/arm64 ARM-образ и зависимости уже поддержаны Отдельный проект может не иметь ARM-рецептов
Multi-platform Buildx Нужно публиковать один тег для разных машин Одна стадия может незаметно скачать неверный бинарник
Сборка через эмуляцию Требуется быстро проверить существующий Dockerfile Медленный или нестабильный pipeline
Отдельные Dockerfile Архитектуры требуют разных зависимостей Дублирование логики и расхождение версий
Сохранение только amd64 Есть проверенная Linux-инфраструктура Apple Silicon остаётся режимом временной совместимости

Каждая архитектура должна иметь собственный лог сборки. Сохраняйте также digest опубликованного образа, список платформ и контрольные суммы полученных артефактов. Тег latest недостаточен для научного протокола: он может указывать на другой manifest после публикации новой версии.

Воспроизводимость результата

Контейнер может запуститься и всё равно не воспроизвести результат исследования. Успешный docker run — только техническая проверка входа в среду.

Перед сравнением результатов зафиксируйте:

  • digest образа, а не только его тег;
  • версии системных пакетов;
  • версии Python, R и нативных библиотек;
  • случайное зерно и параметры многопоточности;
  • внешний инструмент, вызываемый из pipeline;
  • входные данные и порядок их обработки;
  • ключевые промежуточные и итоговые файлы.

Сравнивать нужно минимум три сценария, если они доступны:

  • нативный arm64;
  • amd64 через эмуляцию;
  • базовая среда лаборатории на Linux или другой подтверждённой платформе.

Не следует заранее объявлять результаты одинаковыми или разными без принятого проектом критерия. Для одного проекта важен байт-в-байт одинаковый файл, для другого — совпадение идентификаторов, статистических показателей или контрольных метрик. Порог расхождения должен приходить из протокола исследования, документации метода или требований проекта.

Можно ли считать научный результат воспроизводимым, если эмулируемый контейнер запустился? Нет. Запуск подтверждает совместимость конкретного сценария, но не равен проверке численной устойчивости, случайности, внешних инструментов и входных данных. Эмуляция может быть полезной контрольной точкой, но долгосрочную базовую среду следует выбирать после сравнения результатов.

Проверка без собственного Mac

Как протестировать совместимость Docker-образа с Apple Silicon без Mac? Надёжный путь — получить временный доступ к реальному Apple Silicon Mac, а не делать вывод только по сборке на Linux или Windows. Проверка должна проходить в чистой среде с тем же образом, digest, командами запуска и набором тестовых данных.

Минимальный протокол:

  • [ ] Зафиксировать digest образа и список платформ через docker buildx imagetools inspect.
  • [ ] Записать версию Docker Desktop и параметры запуска.
  • [ ] Запустить нативный linux/arm64-вариант, если он опубликован.
  • [ ] Отдельно проверить linux/amd64, не смешивая его журнал с ARM-тестом.
  • [ ] Сохранить полный вывод docker logs и код завершения.
  • [ ] Проверить архитектуру ключевых бинарников внутри контейнера.
  • [ ] Выполнить короткий тест с контрольными входными данными.
  • [ ] Сопоставить итоговые файлы с лабораторной базовой линией.
  • [ ] Удалить секреты, временные данные и контейнеры после завершения проверки.
  • [ ] Передать команде digest, команды, логи и ограничения найденного сценария.

Документация Docker по известным проблемам Docker Desktop нужна именно на этапе проверки окружения: отдельные ошибки могут относиться к виртуальной машине, файловому обмену или сетевому слою, а не к исследовательскому образу.

Если лаборатория не располагает Mac, временная аренда удалённого Apple Silicon окружения позволяет отделить вопрос «образ совместим с ARM» от вопроса «лаборатории нужно постоянно покупать устройство». Доступ через удалённую консоль и SSH удобен для воспроизводимых команд, но тесту всё равно необходимы журнал, digest и очищенная среда. Без этих материалов результат удалённой проверки трудно передать следующему участнику проекта.

Решение после диагностики

Окончательный выбор удобно принимать по четырём сценариям:

  • Нативная миграция. Есть linux/arm64, зависимости доступны, тестовые результаты проходят критерии проекта.
  • Временная эмуляция. Есть только amd64, нужно локализовать ошибку или проверить короткий сценарий, но среда не назначается базовой для публикации.
  • Двойная поддержка. Проект должен работать и на лабораторном Linux, и на Apple Silicon; публикуются оба варианта, а CI сохраняет отдельные логи.
  • Отложенная миграция. Критическая зависимость не имеет ARM-версии, исходная сборка нестабильна, а эмуляция не проходит критерии результата.

Как понять, что Docker Buildx действительно собрал два варианта? Нужно проверить manifest после публикации, найти в нём linux/arm64 и linux/amd64, затем запустить оба варианта по одному digest-ориентированному сценарию. Один успешный вызов buildx build без проверки registry не подтверждает корректность multi-platform-образа.

Для лаборатории без Mac аренда имеет смысл, если требуется разово принять pull request, воспроизвести ошибку только на Apple Silicon или провести передачу проекта. Покупка устройства оправдана при постоянном локальном тестировании, необходимости физического доступа и регулярной работе без удалённого подключения. Для краткого исследовательского цикла удалённая среда обычно снижает риск купить оборудование до того, как подтверждена реальная потребность.

Если текущая проверка выполняется только на Windows или Linux, она не выявит часть ошибок виртуализации macOS, ARM-ветки manifest и поведения контейнера на Apple Silicon. Поэтому при обязательном Mac-сценарии разумно сначала провести чистую удалённую проверку через консоль ProxyMac, сверить подходящий период в условиях аренды ProxyMac, сохранить логи и лишь затем решать, нужен ли постоянный ресурс. Такой подход не заменяет проектную валидацию, но делает решение проверяемым: вместо предположения остаётся конкретный digest, команда запуска и набор результатов.

Если нужен доступ к Apple Silicon только на время отладки или приёмки контейнера, справочные материалы ProxyMac помогут подготовить удалённую сессию и не смешивать техническую проверку с долгосрочной закупкой.

Проверьте Docker-образы на удалённом Mac с Apple Silicon

ProxyMac предоставляет удалённый Mac для проверки совместимости контейнеров и нативных зависимостей в среде Apple Silicon.
Запускайте сборки и тесты на выделенном устройстве, чтобы повысить воспроизводимость результатов разработки и исследований.