Shehu Awwal

Running x86/AMD64 Docker Container Images On Apple Mac ARM With Colima

Learn how to run x86/AMD64 Docker images on Apple Silicon using Colima for seamless container management.

Containers · Docker · MacOS

4 minutes

December 10, 2024

I’ve really encountered issues most especially switching from Apple Intel processor to Apple Silicon with docker images built specifically for x86/AMD64 but unable to run on the mac.

Likely you might have encountered this issues if the image was built for x86/AMD64, but with docker buildx that allows you to build container images for multi architecture processor becomes easy. How about when the images is old for like 5years or so. Or you specifically need to use an intel x86/AMD64 images.

The case is quite different when you want to run a program/software on your Apple M series with the support of Apple Rosetta 2 and what is Rosetta 2?

Rosetta 2 is a dynamic binary translator developed by Apple as part of their transition from Intel processors to custom ARM-based Apple Silicon chips. It allows x86_64 applications to run natively on ARM-based Macs without requiring developers to rewrite their entire codebase.

And also we need to ensure we have Colima installed on our machine:

Colima is a container runtime that allows you to run Docker and Kubernetes on macOS using lightweight virtual machines. It’s designed to be a simple, efficient alternative to Docker Desktop, especially for developers and users who want more control and less overhead.

I don’t use docker desktop on my system, because it’s slow rather I use Orbstack - https://orbstack.dev which is fast, light, and simple way to run containers and Linux machines. OrbStack offers excellent performance and seamless integration with macOS.

How To Run x86/AMD64 Container Images on Apple Silicon

  • First, You need to ensure you’ve docker and docker compose/docker-compose installed on your system either via homebrew or macports, or instead via the docker desktop or orbstack. The most important thing to have the docker client available on your system.

In this case, I am running Orbstack which is available on my mac.

  • Ensure to have rosetta2 installed on your mac, you can install rosetta if you don’t have it on your mac via terminal.
/usr/sbin/softwareupdate --install-rosetta --agree-to-license
  • We can proceed to install colima
brew install colima

After installing colima, we can then start the vm with: You can modify below command by adding more cpu, memory and disk. You can check for more options with colima start --help

colima start \
    --arch x86_64 \
    --vm-type=vz \
    --vz-rosetta \
    --mount-type=virtiofs \
    --memory 4

Basic Explanation On The Colima Command Above

  1. --arch x86_64

    • Forces the VM to use x86_64 (Intel) architecture
    • Useful for running x86_64 containers on Apple Silicon Macs
    • Enables running Intel-based containers through emulation

  2. --vm-type=vz

    • Uses the Virtualization framework (VZ) on macOS
    • A native macOS virtualization framework introduced in newer versions of macOS
    • Provides more efficient and integrated virtualization compared to older methods

  3. --vz-rosetta

    • Enables Rosetta 2 translation for the virtual machine
    • Allows x86_64 binaries to run on ARM-based Macs
    • Provides seamless translation of Intel instructions to ARM

  4. --mount-type=virtiofs

    • Uses VirtioFS for file system sharing between host and VM
    • More performant than traditional file sharing methods
    • Provides faster and more efficient file access for containers
    • Improves I/O performance for mounted volumes

  5. --memory 4

    • Allocates 4 GB of RAM to the Colima virtual machine
    • Defines the amount of memory available to the container runtime
    • Adjust based on your system resources and workload requirements

This command is particularly useful for:

  • Developers working with x86_64 containers on Apple Silicon Macs

  • Ensuring compatibility with Intel-based container images

  • Optimizing performance through advanced virtualization features

  • We can start the colima vm with colima ssh or colima x or colima exec this logs you in into the vm.

  • When you are into the vm, you can check the processor with:

lima@colima:/Users/shehu.awwal$ uname -a
Linux colima 6.8.0-47-generic #47-Ubuntu SMP PREEMPT_DYNAMIC Fri Sep 27 21:40:26 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux

As you can see we are currently running x86_64.

  • You can proceed to run your docker commands:
lima@colima:/Users/shehu.awwal$ docker pull alpine
lima@colima:/Users/shehu.awwal$ docker inspect alpine | grep -i Architecture
"Architecture": "amd64",

As you can see the alpine image architecture is amd64.


Comments: