ARM64 Docker compatibility matters when you move the applications you rely on to a new server. A web interface may load while a background worker fails, a database extension is unavailable, or inference falls back to the CPU. Checking the complete application before migrating saves time tracking down those failures later.

On Turing Pi 2.5, RK1 and Jetson nodes share a Linux CPU architecture, but their GPU, NPU and media features need different drivers and runtimes. An image that works for an ordinary CPU task may need a different build for hardware acceleration.

In our tests, 29 of 32 image references declared Linux ARM64 support, and five services passed functional checks on RK1. A separate compression test took 16.46 times as long under AMD64 emulation as it did natively on ARM64. That ratio applies to this workload; the checks below show how to assess your own applications. Our self-hosted apps guide covers what you can run.

1. What does ARM64 support actually cover?

Start with the project’s requirements and the exact release you intend to deploy. Immich’s requirements, for example, list both AMD64 and ARM64. Its server, machine-learning service and database still need compatible versions and enough memory.

Hardware-dependent features need a closer check. “Jellyfin with hardware transcoding for your HEVC files” is a useful requirement: it identifies the application, accelerator and codec path you must test. A successful startup answers only part of that question.

Vendor support is another consideration. Microsoft supports SQL Server Linux containers on Intel and AMD x86-64 hosts and excludes emulation from its tested and supported configurations. Getting it to start under emulation doesn’t make it supported.

2. Check the exact Docker image

ARM64, AArch64 and AMD64

On 64-bit ARM Linux, uname -m commonly reports aarch64; Docker uses linux/arm64 for image platforms. Debian and Ubuntu report their userspace architecture through dpkg --print-architecture. amd64 means x86-64, covering both Intel and AMD processors.

Run these commands on the intended Linux node:

uname -m
dpkg --print-architecture
docker context show
docker info --format '{{.OSType}}/{{.Architecture}}'

Check the Docker context: a CLI on your laptop may control a remote daemon. Confirm that the daemon belongs to the node you intend to test.

Inspect the registry before downloading

A multi-platform image groups separate platform builds in a Docker manifest list or OCI image index. Docker selects a matching build when you pull it. Docker’s multi-platform documentation explains that structure.

Inspect the image you intend to deploy:

docker buildx imagetools inspect nginx:stable

Look for linux/arm64, sometimes displayed with a /v8 variant. Check the exact release tag used by your deployment as well. Each tag needs its own check.

The Buildx inspection command queries registry metadata without starting the application. Its output can also contain attestations marked unknown/unknown; these are not additional runnable CPU platforms. A single-platform manifest may require checking its image configuration instead of looking for an index of platforms.

Do not interpret an authentication failure, registry timeout or rate limit as evidence that ARM64 is absent. Those are failed inspections. “No ARM64 variant” requires successfully reading the relevant metadata.

A small ARM64 image checker

Save the following as check_arm64.py and run python3 check_arm64.py IMAGE:TAG. It needs Python 3, Docker CLI and Buildx, and reads registry metadata without pulling image layers. It reports ARM64_DECLARED, NO_ARM64_DECLARED or UNKNOWN.

This version reads manifest lists and OCI image indexes. A single-platform manifest needs a separate configuration check. Failed requests and incomplete entries, including nested indexes, remain UNKNOWN unless another entry explicitly declares Linux ARM64. Exit codes are 0 for ARM64_DECLARED, 1 for NO_ARM64_DECLARED, and 2 for UNKNOWN. A successful check confirms an ARM64 declaration; test the application separately.

#!/usr/bin/env python3
"""Small registry index checker. A single manifest needs a separate config check."""
import json
import subprocess
import sys

def check(ref):
    if not ref or ref.startswith("-") or any(c.isspace() for c in ref):
        return "UNKNOWN"
    try:
        run = subprocess.run(
            ["docker", "buildx", "imagetools", "inspect", ref, "--raw"],
            capture_output=True, text=True, check=True, timeout=90)
        doc = json.loads(run.stdout)
        index_types = (
            "application/vnd.oci.image.index.v1+json",
            "application/vnd.docker.distribution.manifest.list.v2+json",
        )
        if not isinstance(doc, dict) or doc.get("mediaType") not in index_types:
            return "UNKNOWN"
        entries = doc.get("manifests") if isinstance(doc, dict) else None
        if not isinstance(entries, list) or not entries:
            return "UNKNOWN"
        unknown, runnable = False, 0
        for entry in entries:
            if not isinstance(entry, dict):
                unknown = True
                continue
            annotations = entry.get("annotations") or {}
            platform = entry.get("platform") or {}
            if not isinstance(annotations, dict) or not isinstance(platform, dict):
                unknown = True
                continue
            if annotations.get("vnd.docker.reference.type") == "attestation-manifest":
                continue
            media = entry.get("mediaType", "")
            if media not in ("application/vnd.oci.image.manifest.v1+json",
                             "application/vnd.docker.distribution.manifest.v2+json"):
                unknown = True
                continue
            os_name, arch = platform.get("os"), platform.get("architecture")
            if (not isinstance(os_name, str) or not isinstance(arch, str)
                    or not os_name or not arch or "unknown" in (os_name, arch)):
                unknown = True
            elif (os_name, arch) == ("linux", "arm64"):
                return "ARM64_DECLARED"
            else:
                runnable += 1
        return "UNKNOWN" if unknown or not runnable else "NO_ARM64_DECLARED"
    except subprocess.CalledProcessError as error:
        print(error.stderr.strip() or str(error), file=sys.stderr)
        return "UNKNOWN"
    except (OSError, subprocess.SubprocessError, ValueError) as error:
        print(str(error), file=sys.stderr)
        return "UNKNOWN"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python3 check_arm64.py IMAGE:TAG", file=sys.stderr)
        raise SystemExit(2)
    result = check(sys.argv[1])
    print(result)
    raise SystemExit({"ARM64_DECLARED": 0, "NO_ARM64_DECLARED": 1,
                      "UNKNOWN": 2}[result])

For UNKNOWN, read any error printed to stderr and rerun docker buildx imagetools inspect IMAGE:TAG to examine the response. For a single-platform image, Buildx can expose its configuration:

docker buildx imagetools inspect IMAGE:TAG --format '{{json .Image}}'

Check the configuration’s os and architecture fields. If the command cannot retrieve them, keep the result unresolved.

For Docker Hub authentication, run docker login before retrying. Authentication uses your account’s allowance; it does not remove every rate limit. Docker documents pull limits and authentication.

Record what you actually pulled

Once you have selected a suitable image:

docker pull --platform linux/arm64 nginx:stable
docker image inspect nginx:stable \
  --format '{{.Os}}/{{.Architecture}} {{json .RepoDigests}}'

The examples use stable for discovery. For deployment, retain the tested version and digest so a later tag change does not silently replace it.

Record the image-index digest and selected ARM64 child digest separately when both exist. An index identifies the platform collection; a child digest identifies one member. Docker’s image reference documentation explains digest-based references.

3. Audit the entire application stack

A Compose application can contain a frontend, API, database, cache, worker and migration job. The main application’s image is only one of them.

In the directory containing the intended Compose configuration, use the same overrides, environment file and profiles you will use for deployment:

docker compose config --images

This prints the resolved image references. Inspect each one. The Compose configuration command resolves the configuration model, including variable substitutions and merged files.

Also inspect services with build: instructions. Their Dockerfiles may download precompiled tools, use architecture-specific base images, or copy an x86 binary from a build stage. An image-name list cannot audit those steps for you.

Watch for an explicit platform override:

platform: linux/amd64

That setting asks Compose to use an x86-64 target. It does not add native ARM64 support. Compose’s platform setting influences the selected image and build target. Do not remove it blindly: first establish why the application author included it and whether a native replacement exists.

Our Gitea deployment guide pairs the application with PostgreSQL and persistent storage. Test the combination by pushing a disposable commit, reading it back and checking it after a restart.

Python dependencies can be the missing piece

An ARM64 Python interpreter does not guarantee that every package has a suitable binary distribution. A compiled wheel can depend on the Python version, ABI, CPU architecture and Linux C library. PyPA distinguishes manylinux wheels for compatible glibc environments from musllinux wheels for musl-based environments such as Alpine. The wheel compatibility specification describes those tags.

Inside the intended Python environment, a useful early check is:

python -m pip download --only-binary=:all: \
  --dest wheel-check -r requirements.txt

Use the application’s pinned requirements and package indexes. This pip command requires compatible wheels. If resolution fails, check for missing wheels, version conflicts or authentication errors before considering a source build.

If you build from source, retain the source revision, compiler and dependency versions so the next release can be rebuilt.

CI jobs need their own audit

An ARM64 runner can launch a workflow that later downloads an x86-only executable or invokes an AMD64 Docker action. Audit the job images and downloaded tools as well as the runner image.

Use the Gitea Actions guide for runner setup, then verify that your required job completes on ARM64.

4. Check the accelerator separately

Jetson: an ARM64 build is not a CUDA guarantee

For Jetson inference, verify the host platform, framework build and GPU execution path together. NVIDIA’s PyTorch installation guidance ties its packages to specified JetPack releases. Select from the matching compatibility information instead of assuming that any Linux ARM64 wheel or NVIDIA container will suit the module.

In the exact environment that will run the application, a small execution check is more informative than a successful import:

import torch

print("PyTorch:", torch.__version__)
print("Build CUDA:", torch.version.cuda)
print("CUDA available:", torch.cuda.is_available())
if not torch.cuda.is_available():
    raise SystemExit("CUDA unavailable in this environment")

x = torch.arange(1024, device="cuda", dtype=torch.float32)
result = (x * 2).sum()
torch.cuda.synchronize()
assert result.item() == 1047552.0
print("Device:", torch.cuda.get_device_name(0))
print("CUDA operation passed")

This checks GPU execution and a known result. Follow it with the model operators, TensorRT engine and memory demand your application actually needs.

Our Jetson software-stack explainer and GPU-container preparation guide cover the platform setup. Reinstalling that stack should not be the first response to an incompatible application image.

Match the JetPack packaging, not just the CPU label

Older Jetson tutorials often start from nvcr.io/nvidia/l4t-base. A May 2024 reply in NVIDIA’s JetPack 6.0 announcement thread said no further L4T base-container releases were planned. Treat an old l4t-base recipe as a release-specific recipe, rather than a current default.

Check the host before selecting a wheel or container:

cat /etc/nv_tegra_release
dpkg-query -W nvidia-l4t-core nvidia-jetpack

The JetPack metapackage can be absent on a working system. Record the installed L4T and compute packages as well as the module; select a framework build whose documentation covers that combination.

As of October 29, 2026, NVIDIA’s PyTorch compatibility table listed JetPack 7.1 for framework releases 26.01 through 26.09, with no 7.2.1 row. The same page says standalone iGPU containers end starting with release 26.03. An old -igpu tag convention is therefore not a reliable way to select newer releases.

Our Jetson Orin Nano check reused an existing virtual environment with PyTorch 2.12.0+cu132 and torchvision 0.27.0+cu132. The host reported nvidia-jetpack 7.2.1-b49, nvidia-l4t-core and nvidia-l4t-cuda version 39.2.1-20260806224157, and CUDA 13.2. A CUDA reduction and matrix product passed. No model inference was run.

NVIDIA’s compatibility table does not list JetPack 7.2.1, so treat this as a smoke test rather than a recommended setup.

PyTorch also warned that the Orin GPU’s compute capability, 8.7 (sm_87), was outside the build’s listed targets. This is a GPU architecture warning, separate from the CPU’s ARM64 label. Passing two operations leaves other operators and models untested. Inspect the GPU capability and the build’s compiled architecture list with:

import torch

print("GPU capability:", torch.cuda.get_device_capability(0))
print("Build architectures:", torch.cuda.get_arch_list())

Run this after confirming CUDA is available. PyTorch documents these inspection functions.

RK1: media and NPU features have different requirements

The RK1’s ARM CPU, Rockchip media hardware and NPU are separate execution targets. A container built for the CPU does not automatically use the other engines.

Jellyfin’s Rockchip documentation specifies RKMPP and the required kernel and devices. Follow the RK3588 transcoding guide, then test a file that requires transcoding.

For the NPU, verify three pieces together: the kernel’s RKNPU driver and device access, the librknnrt.so loaded by the application, and a model built for RK3588 with a compatible toolchain. Rockchip’s Model Zoo documents release dependencies and RK3588 examples. Choose the example release that fits your installed runtime, rather than upgrading the node to match the newest demo.

Discover the device on the actual node. In a DRM-based setup, this read-only check maps render devices to their drivers:

for dev in /sys/class/drm/renderD*; do
  [ -e "$dev" ] || continue
  printf '%s -> ' "$dev"
  readlink -f "$dev/device/driver"
done

Use the driver mapping to identify the NPU; a render device can belong to another engine. Other kernel stacks can expose different paths. Pass only the verified device and required group permissions to the container.

Rockchip’s RKNN API exposes RKNN_QUERY_SDK_VERSION. Capture its api_version and drv_version, check that SDK release’s compatibility guidance, and run a known RK3588 fixture. The two version strings can differ.

On our RK1, /dev/dri/renderD129 mapped to RKNPU. The official RKNN Toolkit 2 v2.0.0-beta0 runtime reported API 2.0.0b0 with the installed driver 0.9.7. The official MobileNet fixture ran natively on the NPU and returned class 156 (Shih-Tzu), score 0.892578125, for the 224 × 224 sample. This check covered one fixture, without measuring throughput.

Frigate’s installation documentation distinguishes general ARM64, Rockchip and Jetson image variants. As of October 29, 2026, its listed Jetson option is the community-supported stable-tensorrt-jp6 build for JetPack 6; the list has no JetPack 7 counterpart. Match the image to the host’s JetPack release before testing GPU acceleration.

5. A practical audit on Turing Pi 2.5

What a dated registry sample tells us

On October 27, 2026 (UTC), we inspected 32 image references across 31 projects, counting Immich’s server and machine-learning images separately. Nineteen references come from Docker’s Official Images namespace, docker.io/library. This selection favors established infrastructure and self-hosted software. The 29-of-32 result describes that sample, rather than the share of all Docker images that support ARM64. Tags such as latest and stable were discovery references; deployments need tested versions and digests.

The first pass returned 12 ARM64 declarations, two references without ARM64 and 18 UNKNOWN results. We hit Docker Hub’s anonymous rate limit; retries resolved all 18 unknowns, bringing the final totals to 29 ARM64, three without ARM64 and zero unknown. A failed request can look like a missing image if the checker treats both as the same result.

These are registry declarations, not results from running all 32 images. The scan read metadata without downloading image layers. The table preserves the tag names used for discovery.

The three “No” results came from the image configurations: pytorch/pytorch:latest, tensorflow/tensorflow:latest and mcr.microsoft.com/mssql/server:2022-latest each identified os: linux and architecture: amd64. They use single-platform manifests, so the small checker above returns UNKNOWN for them. The separate --format '{{json .Image}}' check establishes their architecture.

ProjectImage reference checkedLinux ARM64 variant
nginxnginx:stableYes
caddycaddy:latestYes
traefiktraefik:latestYes
httpdhttpd:latestYes
haproxyhaproxy:latestYes
postgrespostgres:latestYes
mysqlmysql:latestYes
mariadbmariadb:latestYes
mongomongo:latestYes
redisredis:latestYes
valkeyvalkey/valkey:latestYes
memcachedmemcached:latestYes
rabbitmqrabbitmq:latestYes
natsnats:latestYes
nextcloudnextcloud:latestYes
wordpresswordpress:latestYes
ghostghost:latestYes
pythonpython:latestYes
nodenode:latestYes
golanggolang:latestYes
Giteadocker.gitea.com/gitea:latestYes
Home Assistantghcr.io/home-assistant/home-assistant:stableYes
Jellyfinjellyfin/jellyfin:latestYes
Immich serverghcr.io/immich-app/immich-server:releaseYes
Immich machine learningghcr.io/immich-app/immich-machine-learning:releaseYes
Ollamaollama/ollama:latestYes
Open WebUIghcr.io/open-webui/open-webui:mainYes
vLLMvllm/vllm-openai:latestYes; NVIDIA CUDA GPU image
PyTorchpytorch/pytorch:latestNo
TensorFlowtensorflow/tensorflow:latestNo
Frigateghcr.io/blakeblackshear/frigate:stableYes
SQL Servermcr.microsoft.com/mssql/server:2022-latestNo

vLLM: The ARM64 variant belongs to the NVIDIA CUDA image. Upstream’s ARM64 build examples target Grace-Hopper and Grace-Blackwell servers. RK1 has no NVIDIA CUDA GPU, and an ARM64 declaration alone does not establish Jetson Orin compatibility. Choose a build documented for the intended GPU and software stack.

PyTorch: The latest tag still identified PyTorch 2.2.1 with a February 2024 image creation date when checked on October 29, 2026. A separate check of the newer pytorch/pytorch:2.14.1-cuda13.2-cudnn9-runtime tag also returned a single-platform AMD64 image. This additional check is outside the original 32-reference sample. Use the project’s versioned tags when choosing a release; the name latest is not a reliable indication of its age.

Run the required features

Record image availability, functional results and vendor support separately. For this ARM64 Docker compatibility audit, we ran the following five service checks.

The five container checks and RKNN inference ran on one RK1 with Ubuntu 24.04.1 LTS, kernel 6.1.0-1025-rockchip, 15 GiB of reported RAM, Docker 29.1.3 and Compose 2.40.3. The service tests used digest-pinned ARM64 images and disposable data. PostgreSQL and Gitea stored that data in host bind mounts on the RK1. These were application and restart checks, not storage benchmarks.

The CUDA check ran separately on a Jetson Orin Nano with Ubuntu 24.04.5 LTS, kernel 6.8.12-1021-tegra and 7.4 GiB of reported RAM. Its software stack is recorded in the Jetson section above.

ApplicationActual result on the intended nodeScope and support limits
NginxPASS. ARM64 Nginx 1.30.6 served the synthetic file over loopback with HTTP 200; the response hash matched the source.The official image supports ARM64; this check covers startup and one HTTP response.
PostgreSQLPASS. ARM64 PostgreSQL 18.6 returned the inserted row after restarting the same container; the container ID was unchanged.This confirms one row on the test’s bind-mounted data path, not database extensions or production durability.
RedisPASS. ARM64 Redis 8.10.2 returned OK for SET and the expected value for GET. Persistence was disabled.This covers an in-memory round trip only.
Gitea with PostgreSQLPASS. The pinned Gitea 1.25.5 image created a test account and repository, accepted a synthetic push, and returned the same commit and file hash after restarting both containers.This covers a small Git-over-HTTP flow and test-data persistence, not Actions, plugins or a production configuration.
Home Assistant ContainerPASS. Version 2026.10.4 passed the official configuration check and returned its 3,188-byte first-run onboarding page over loopback with HTTP 200.This confirms startup and minimal configuration, not integrations or long-term stability.

All five container checks passed. For a new deployment, choose a currently maintained release and repeat these checks with your own configuration. The checks ran sequentially and used small, disposable datasets. They establish the listed behaviors, without measuring concurrent capacity, production load or long-term stability.

6. Can you run x86 Docker images on ARM64?

Yes, some x86 Docker images can run on ARM64 using emulation. QEMU’s user-mode emulator can execute programs built for another CPU architecture while translating their interaction with the host system. This can be useful for a small tool that has no native build.

Docker warns that emulated builds can be much slower for CPU-heavy work such as compilation and compression. There is no single slowdown factor that applies to every application. Emulation also does not create vendor support: Microsoft’s SQL Server container policy still excludes that configuration.

What emulation cost in our compression test

On October 27, 2026 (UTC), five alternating pairs compared digest-pinned Python 3.13.18 Debian Bookworm images on the same RK1, with both paths pinned to CPU 4. Each trial compressed the same 16 MiB synthetic input 20 times at zlib level 6. Python, compiler and zlib versions matched; every run produced the same 7,986,164-byte output and passed the decompression check.

PathMedian timeRange across five trials
Native ARM646.013 s5.995 to 6.027 s
AMD64 under QEMU (QEMU_CPU=max)98.974 s98.902 to 99.369 s

The median emulated time divided by the median native time is 16.46×. The emulator was QEMU 10.2.3, with QEMU_CPU=max; CPU 4 used its existing performance governor and a maximum frequency of 2.304 GHz. Each new pair reversed which architecture ran first. The timer covers only the compression loop; pulls, container startup, input generation, warm-up and decompression are excluded. This is one synthetic workload on one RK1. The ARM64 and AMD64 builds can use different architecture-specific optimizations, so the result is not a pure QEMU overhead factor or a prediction for other tasks.

The reproduction section below includes the Python probe and image pins. The input SHA-256 is b76ca42e2820cff782713f8dcd0bf3e90527189563e2cfbf2544e3a97f0fd0bb; the expected compressed size is 7,986,164 bytes. Use those checks when comparing runs.

Reproduce the compression workload

Use an otherwise idle ARM64 Linux host, Docker and a working QEMU AMD64 execution path. Docker’s QEMU setup documentation describes the binfmt prerequisites. Confirm the actual emulator process and version before collecting results; a platform flag or a label in the output does not establish which execution path ran.

The measured run used these children of python:3.13.18-slim-bookworm:

PlatformPinned image
ARM64docker.io/library/python@sha256:fb12d5e51ef10ac4bc3c0b669166bbc16487cd918543ca7e6e0a899e22c550ae
AMD64docker.io/library/python@sha256:89c04d97d1f3f0a04ea357a27d000ba4efb18536d2d68a54611f76d5c1b5fe99

Both reported Python 3.13.18, GCC 12.2.0 and zlib 1.2.13. Save the following as compression_probe.py. It generates the input, performs one untimed warm-up, times the compression loop and checks decompression afterward.

#!/usr/bin/env python3
"""One bounded zlib trial. The caller alternates architectures; this never invokes Docker."""
import argparse
import datetime as dt
import hashlib
import json
from pathlib import Path
import platform
import sys
import time
import zlib

def payload_bytes(size):
    # Deterministic mixed-repetition synthetic bytes; NOT a production backup corpus.
    # This generation step is outside timing. Input digest must agree across architectures.
    block = b"".join(hashlib.sha256(f"tp-arm64-audit:{i}".encode()).digest()
                     for i in range(4096))
    data = (block + b"Turing Pi ARM64 compatibility audit\n" * 4096)
    return (data * ((size // len(data)) + 1))[:size]

def main():
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("--mib", type=int, default=16)
    p.add_argument("--loops", type=int, default=20)
    p.add_argument("--level", type=int, default=6, choices=range(10))
    p.add_argument("--trial", required=True)
    p.add_argument("--path-label", required=True, choices=["native-arm64", "emulated-amd64", "local-validation"])
    args = p.parse_args()
    if not 1 <= args.mib <= 64 or not 1 <= args.loops <= 1000:
        p.error("mib must be 1..64; loops must be 1..1000")
    data = payload_bytes(args.mib * 1024 * 1024)
    digest = hashlib.sha256(data).hexdigest()
    warmup = zlib.compress(data, args.level)
    if zlib.decompress(warmup) != data:
        raise RuntimeError("Warm-up round trip failed")
    del warmup
    started = time.perf_counter_ns()
    for _ in range(args.loops):
        compressed = zlib.compress(data, args.level)
    elapsed = (time.perf_counter_ns() - started) / 1e9
    if zlib.decompress(compressed) != data:
        raise RuntimeError("Measured output round trip failed")
    print(json.dumps({
        "schema_version": 1, "trial": args.trial, "path_label": args.path_label,
        "recorded_at_utc": dt.datetime.now(dt.timezone.utc).isoformat(),
        "python": platform.python_version(), "python_build": platform.python_build(),
        "python_compiler": platform.python_compiler(), "machine_reported": platform.machine(),
        "zlib_compile": zlib.ZLIB_VERSION, "zlib_runtime": zlib.ZLIB_RUNTIME_VERSION,
        "input_bytes": len(data), "input_sha256": digest,
        "level": args.level, "loops": args.loops, "warmups": 1,
        "compression_seconds": elapsed,
        "processed_mib_per_second": (len(data) * args.loops / (1024 * 1024)) / elapsed,
        "compressed_bytes": len(compressed), "roundtrip_ok": True,
        "script_sha256": hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
        "timing_scope": "zlib.compress loop only; excludes generation, warm-up, verification, startup and pulls",
        "native_or_emulated_not_verified_by_script": True
    }, sort_keys=True))

if __name__ == "__main__":
    main()

The probe’s SHA-256, including its final newline, is c377434976e7e9b267f355a8c09ef6d73c53bf9e38c947811150978c76480d81. It reports the input hash, compressed size, software versions and elapsed time as JSON.

Pull both pinned images before measuring. Run the probe in each container with --mib 16 --loops 20 --level 6, a unique --trial value and the appropriate --path-label. Mount the script read-only, disable container networking and pin both paths to the same CPU. Our run used CPU 4, its existing performance governor, and QEMU_CPU=max for AMD64.

Collect five pairs in this order: native then emulated, emulated then native, native then emulated, emulated then native, native then emulated. Require ten successful records with roundtrip_ok: true, matching input hashes, script hashes, compression settings and compressed sizes. Compare the Python, compiler and zlib versions as well. Divide the median of the five emulated times by the median of the five native times.

Different hardware, emulator versions or architecture-specific builds can change the result. Use a representative application task for the final deployment decision.

Choose a maintainable workaround

For a missing image, check for a supported native package, maintained alternative image or documented source build. Cross-compilation is another option where the build system supports it; test the resulting artifact on the target hardware.

For an occasional utility, a measured emulation path may be acceptable. For an essential service that remains x86-only or explicitly unsupported, keeping that service on an x86 host is often the simpler operational decision.

On Turing Pi 2.5, choose a node for each supported workload: application services on an RK1 and validated CUDA inference on a Jetson, communicating over the board’s network. Each node still needs its own compatible software and sufficient memory.

7. What to check before buying an ARM server

Before choosing modules, make a short list of the applications you cannot replace. For each one, record:

  1. Exact release and deployment method. Container, native package or source build.
  2. Every required component. Include databases, workers, plugins, migration jobs and CI tools.
  3. The feature that makes it useful. Hardware transcoding, a database extension, CUDA inference or USB access.
  4. The supported platform. CPU architecture, operating system, kernel and accelerator stack.
  5. An acceptance test. A task with an observable correct result, plus restart persistence where data matters.
  6. The fallback. Another supported build, another application, measured emulation, or a separate host.

Then size memory and NVMe storage for the working stack. Compatibility and capacity are different questions: a fully compatible application can still run out of memory or saturate storage. Our Jetson 8GB model-capacity tests cover that next decision for local LLMs.

Troubleshooting

SymptomLikely cause and checkFix
no matching manifest for linux/arm64The selected tag lacks a matching variant, or the platform override is wrong. Inspect it with docker buildx imagetools inspect IMAGE:TAG.Select a documented ARM64 tag or native package. Keep authentication and network failures classified as unresolved.
exec format errorA bundled executable targets another CPU, or a script has a bad interpreter line. Run file ./program, readelf -h ./program for ELF files, and head -n 1 ./script.Replace the binary with the correct architecture build. For a script, correct its shebang/line endings and provide the interpreter. For intentional x86 execution, check the emulator separately below.
Intentional AMD64 execution fails on ARM64The binfmt handler is absent or disabled. Check ls /proc/sys/fs/binfmt_misc and, when present, cat /proc/sys/fs/binfmt_misc/qemu-x86_64; container use commonly needs the F flag.Prefer a native image. If emulation is required, configure the documented handler on a dedicated test host and verify a small process before the real workload.
illegal instructionThe build expects CPU features the target lacks. Compare lscpu with the project’s binary requirements.Choose a build for the supported CPU baseline or rebuild with appropriate target flags. Avoid reusing a build compiled with -march=native on a different CPU.
Python package installation failsWheel tags or dependency constraints differ. Run python -m pip debug --verbose and the wheel-only download check above.Choose a compatible Python/package version or glibc-based image where the project supplies wheels; otherwise use its documented source build. Fix index credentials when the error is authentication.
PyTorch imports but CUDA is unavailableA CPU-only wheel, missing device access or mismatched Jetson stack. Inspect torch.version.cuda, torch.cuda.is_available() and installed L4T packages.Select a documented Jetson framework build and correct container runtime/device access; rerun the CUDA operation.
RKNN cannot initialize the NPUDevice permissions, runtime/driver compatibility or model target differs. Check the driver mapping, actual loaded library and RKNN version query.Grant access to the verified device; select compatible runtime/model artifacts. Don’t replace the NPU driver as part of a quick test on a shared node.
Video plays but transcoding uses the CPUDirect play and hardware transcoding exercise different paths. Inspect Jellyfin’s FFmpeg log for the selected decoder/encoder.Use the documented RKMPP-enabled FFmpeg and device setup, then test a file that actually requires transcoding.
A background job fails after the web app startsWorker images, plugins or downloaded tools have different requirements. Use docker compose config --images and docker compose logs SERVICE.Replace or rebuild the failing component for ARM64 and rerun that job, including its dependencies.

file, readelf (from binutils) and lscpu must be available in the diagnostic environment. Inspect extracted binaries from a disposable container when a minimal image lacks these tools; installing tools into a production service changes what you are testing.

What You’ve Built

Record the tested image digest, dependencies, host versions and acceptance-test result alongside your Compose configuration. When a release changes, repeat the affected checks before replacing the working service. That gives your next ARM64 Docker compatibility review a concrete starting point.

Related Articles

FAQ

How do I check whether a Docker image supports ARM64?

Run docker buildx imagetools inspect IMAGE:TAG and look for the Linux ARM64 variant. Inspect the exact tag you plan to use. For a single-platform image, check the image configuration. Registry metadata confirms packaging, not application behavior.

Does platform: linux/amd64 make an image work on ARM64?

It selects the AMD64 target. Running that image on ARM64 generally needs a configured emulation path, and the application can still fail or remain unsupported.

Can the same image run on RK1 and Jetson?

An ordinary Linux ARM64 CPU application may run on both when its other requirements match. CUDA, Rockchip NPU and media acceleration need their own hardware-specific support. Test those features on the intended node.

Does an ARM64 image guarantee GPU or NPU acceleration?

No. The platform label describes the CPU and operating-system target. Verify the application’s selected backend and execute a representative accelerated task.

Does working on an Apple silicon Mac prove it will work on an RK1?

No. Check whether you ran a native macOS application, a Linux ARM64 container, or an emulated x86 container. Then verify the Linux deployment’s kernel, devices and accelerator requirements on the RK1 itself.

When should I keep an x86 machine?

When a required application or feature has no maintainable native ARM64 path, or when its vendor requires x86. A mixed setup can be more useful than forcing every service onto the same architecture.