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

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

Building ARM Images on Docker x86

When you need to create Docker images for ARM on an x86 machine, you can use QEMU to emulate the ARM architecture during the build process.

Preparation

Before starting, make sure Docker and the QEMU emulator are installed on your development machine. Verify their installation with the following commands:

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

First, download a base image that supports the ARM architecture, for example:

docker pull arm32v7/ubuntu

2. Create a Dockerfile

Write a Dockerfile to build the ARM image. A simple example:

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

3. Enable QEMU support

To allow Docker on an x86 host to build ARM images, add QEMU support in the Dockerfile:

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

4. Build the image

Now build the ARM image on the x86 machine:

docker build -t your-arm-image .

5. Test the image

Run the built ARM image to verify it works in the simulated ARM environment: docker run --rm -it your-arm-image /bin/bash By following these steps you can successfully build Docker images for the ARM architecture on an x86 machine, speeding up development and testing for ARM‑based devices.

Use Case

Assume you have an IoT project based on a Raspberry Pi and you want to develop and test a Python application on an x86 workstation. Building an ARM image on x86 lets you test the application in an emulated ARM environment before deploying to the device.

Example Code

1. Write a simple Python application

Create a file app.py with the following content:

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

2. Create a Dockerfile

Write a Dockerfile to build an ARM‑compatible image for the Python app:

FROM arm32v7/python:3.8-slim
# Set QEMU support
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 application start command
CMD ["python", "app.py"]
RUN [ "cross-build-end" ]

3. Build the Docker image

Execute the following command to build the image for Raspberry Pi:

docker build -t arm-python-app .

4. Run the ARM image

Run the built image and view the output: docker run --rm arm-python-app These steps demonstrate how to build and run an ARM Docker image on an x86 platform, allowing you to test your Python application in an ARM environment early in the development cycle.

ARM images are Docker images optimized for devices that use the ARM processor architecture, which is common in mobile, embedded, and IoT devices. Compared with traditional x86 images, ARM images use a low‑power, efficient instruction set, making them suitable for a wide range of hardware platforms. Building ARM images typically involves cross‑compilation and QEMU emulation to ensure the resulting image runs correctly on ARM devices.