How to Build ARM Docker Images on an x86 Machine Using QEMU

In some scenarios you need to build Docker images for the ARM architecture on an x86 machine, such as when developing for embedded ARM devices or Raspberry Pi. This article shows how to use the QEMU emulator to achieve that.

Preparation

Before starting, ensure Docker and QEMU are installed on your development machine. Verify their installation with:

docker -v
qemu-arm-static -version

If they are not installed, follow the official documentation to install them.

Steps

1. Pull an ARM base image

Download an ARM‑compatible base image from Docker Hub, for example:

docker pull arm32v7/ubuntu

2. Create a Dockerfile

Write a Dockerfile to build the ARM image:

FROM arm32v7/ubuntu
RUN apt-get update && apt-get install -y <your-package>

3. Enable QEMU support

Add QEMU to the Dockerfile so the x86 host can build ARM images:

COPY /usr/bin/qemu-arm-static /usr/bin
RUN [ "cross-build-start" ]
RUN <your-build-commands>
RUN [ "cross-build-end" ]

4. Build the image

Build the ARM image on the x86 machine:

docker build -t your-arm-image .

5. Test the image

Run the built image to verify it works in the simulated ARM environment:

docker run --rm -it your-arm-image /bin/bash

Application Scenario

For a Raspberry Pi IoT project, you may want to develop and test a Python application on x86 before deploying to the device.

Example Code

1. Simple Python app

Create app.py with the following content:

print("Hello, this is running on ARM architecture!")

2. Dockerfile for the Python app

FROM arm32v7/python:3.8-slim
# Enable QEMU
COPY /usr/bin/qemu-arm-static /usr/bin
RUN [ "cross-build-start" ]
# Install Python dependencies
RUN pip install flask
# Copy application code
COPY app.py /
# Set the start command
CMD ["python", "app.py"]
RUN [ "cross-build-end" ]

3. Build the Docker image

docker build -t arm-python-app .

4. Run the ARM image

docker run --rm arm-python-app

These steps successfully build an ARM Docker image on an x86 platform and run a Python application inside the simulated ARM environment, allowing developers to test ARM‑specific behavior early.

ARM images are optimized for devices using the ARM processor architecture, which is common in mobile, embedded, and IoT devices due to its low power consumption and efficiency. Building ARM images on x86 involves cross‑compilation and QEMU emulation to ensure compatibility.