The transition to Apple Silicon, specifically the M1, M2, and M3 series of chips, introduced a fundamental shift in the computing landscape for developers. By moving from the x86_64 (Intel) architecture to the ARM64 architecture, Apple necessitated a corresponding shift in how software, and specifically containerized applications, are deployed. One of the most prominent friction points during this transition has been the deployment of MySQL via Docker. For a significant period, developers encountered a catastrophic failure when attempting to pull official MySQL images on M1 Macs, resulting in the dreaded "no matching manifest for linux/arm64/v8" error. This discrepancy exists because Docker images are not universal; they are built for specific CPU instruction sets. When a user requests an image, Docker checks the manifest list to see if a version exists that matches the host's architecture. If the manifest only contains amd64 (Intel/AMD) and the host is arm64 (Apple Silicon), the pull operation fails. Understanding this architectural gap is critical for any developer attempting to establish a local database environment on modern macOS hardware.

The Anatomy of the Manifest Error

When a user executes a command such as docker pull mysql:8.0.23 or docker run --name mysqlbd1 -e MYSQL_ROOT_PASSWORD=bootcamp -p "3307:3306" -d mysql on an Apple M1 MacBook, they may encounter a specific failure message: no matching manifest for linux/arm64/v8 in the manifest list entries.

The technical layer of this error resides in the Docker Image Manifest. A manifest is essentially a JSON file that acts as a directory for the image. In multi-architecture images, the manifest list points to different image digests based on the operating system and the CPU architecture. In the case of older MySQL versions, such as 8.0.23 or 5.7, the manifest list did not include an entry for linux/arm64/v8. Consequently, the Docker Engine on an M1 Mac, which specifically looks for arm64 compatibility, finds no match and terminates the process.

The real-world impact for the user is a complete inability to instantiate the database container. For a student or a professional developer, this means their local development environment is broken, preventing the execution of any application that relies on a MySQL backend. This creates a paradoxical situation where the command works perfectly on a colleague's Intel-based MacBook or a cloud-based Linux instance, but fails on the newer, more powerful Apple Silicon hardware.

To diagnose these issues before attempting a pull, developers can utilize the mquery tool. This utility allows a user to query any public image in a public container repository to verify its media type (whether it is a standard OCIv1 or Docker v2.2 image), its digest, and, most importantly, its platform support. By checking the platform support via mquery, a developer can determine if an image is an OCI index or a Docker v2.2 manifest list and whether it explicitly supports arm64.

Evolution of MySQL ARM Support

The landscape of MySQL compatibility on ARM64 has shifted significantly over time. As of mid-2021, the official MySQL images lacked native support for ARM64 CPUs, which directly impacted all M1+ Mac users. This gap created a period of instability where developers had to rely on workarounds or alternative images.

However, as of late 2022, a critical update occurred: MySQL 8+ now provides native support for both amd64 and arm64 CPU architectures out of the box. This means that for current versions of MySQL 8, Docker will automatically detect the Apple Silicon architecture and pull the correct arm64 variant without requiring any manual intervention from the user.

It is important to note the status of legacy versions. Specifically, there is no arm64 support for MySQL 5.7. Because MySQL 5.7 was slated for end-of-life in October 2023, the technical recommendation for all M1+ users is to upgrade to MySQL 8+ to ensure native architectural compatibility and continued security support.

The following table delineates the architectural support across different MySQL versions and platforms:

Strategic Workarounds for Architecture Mismatches

For developers who are forced to use specific older versions of MySQL that do not have native ARM64 manifests, several strategic maneuvers can be employed.

The Platform Flag Emulation

One method to bypass the manifest error is to explicitly tell Docker to use the amd64 platform. This is achieved by adding the --platform flag to the command line.

Example command:
docker run --platform linux/amd64 -e MYSQL_ROOT_PASSWORD=password -d mysql:8.0.27

Or for pulling the image:
docker pull --platform=linux/amd64 mysql:8.0.27

The technical mechanism here is emulation. Docker Desktop for Mac utilizes a virtualization layer that allows it to run amd64 containers on arm64 hardware. While this allows the image to be pulled and the container to start, it is not without risks. Emulation can lead to significant performance degradation and, in some cases, instability. As evidenced by community reports, even after successfully pulling an amd64 image using the platform flag, subsequent docker compose up commands may still fail if the docker-compose.yml file does not also specify the platform, or if the underlying build process encounters a conflict during the creation of the container.

Migration to MariaDB

Given the compatibility between MySQL and MariaDB, switching to MariaDB is a highly effective solution for ARM64 users. MariaDB has historically provided robust support for ARM containers, making it a seamless drop-in replacement for many MySQL-based applications.

The impact of this change is minimal for most users, as MariaDB maintains a high degree of protocol compatibility with MySQL. For a developer on an M1 Mac, switching to an image like mariadb:10.6.4-focal ensures that the container runs natively on the ARM64 architecture, providing full performance and stability without the need for emulation.

Implementing Dynamic Image Selection with Environment Variables

In a professional team environment, developers often use a mix of hardware: some on Windows with WSL 2, some on Intel Macs, some on native Linux, and some on Apple Silicon (M1/M2/M3). Hardcoding a specific image in a docker-compose.yml file can break the workflow for a segment of the team.

To solve this, a dynamic image selection pattern using environment variables is recommended. This allows the architecture-specific image to be defined in a local .env file that is not committed to version control.

The implementation involves modifying the docker-compose.yml as follows:

```yaml
services:
db:
image: "${DOCKERMYSQLIMAGE:-mysql:8.0.17}"
volumes:
- "db:/var/lib/mysql"

volumes:
db: {}
```

In this configuration, ${DOCKER_MYSQL_IMAGE:-mysql:8.0.17} tells Docker to use the value of the DOCKER_MYSQL_IMAGE environment variable if it exists; otherwise, it defaults to mysql:8.0.17.

The developer then manages the selection in a .env file:

```bash

If you're using an Intel / AMD CPU (x86-64) you can leave this as the default value,

but if you're using an M1+ CPU (ARM 64) you can use the MariaDB image instead of

MySQL by uncommenting the variable below and setting it to mariadb:10.6.4-focal.

DOCKERMYSQLIMAGE=mysql:8.0.17

DOCKERMYSQLIMAGE=mariadb:10.6.4-focal
```

By using an .env.example file committed to version control, every team member can copy the example to a local .env and set the image that matches their specific hardware architecture. This removes the need to modify the shared compose file and ensures that M1 users can utilize MariaDB while Intel users continue with MySQL.

Advanced Multi-Platform Builds with Buildx

For those creating their own custom MySQL images or wrappers, Docker Buildx is the essential tool for addressing architecture discrepancies. Buildx is a Docker component that leverages the Moby BuildKit builder engine, designed specifically for multi-platform builds.

Unlike the standard docker build command, Buildx allows the user to target multiple architectures simultaneously. This means a developer can build an image that contains variants for both amd64 and arm64, which are then pushed to a registry as a single tag.

The command to execute a multi-platform build is:
docker buildx build --platform linux/amd64, linux/arm64 -t mysql:8.0.23 .

The technical flow of this process is as follows:
1. BuildKit initializes the build for each specified platform.
2. It creates separate binary layers for amd64 and arm64.
3. It wraps these layers into a single manifest list.
4. When a user pulls the image, Docker Desktop identifies the host architecture and selects the corresponding layer.

This is the gold standard for image distribution, as it eliminates the need for end-users to manually specify --platform flags and ensures the most efficient execution of the software on the host CPU.

Practical Execution: Running MySQL Containers

For users who have verified that they are using a compatible version of MySQL (8+ native ARM support) or are using MariaDB, the execution process is straightforward.

To start a basic MySQL instance, use the following command:
docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:tag

In this command:
- some-mysql is the assigned name of the container.
- MYSQL_ROOT_PASSWORD is the environment variable that defines the root password.
- mysql:tag specifies the version (e.g., mysql:8.0).

To interact with the database using the MySQL command-line client within a separate container, the following approach is used:
docker run -it --network some-network --rm mysql mysql -hsome-mysql -uexample-user -p

This command connects the client container to the same network as the database server and attempts to authenticate against the host some-mysql.

Conclusion

The challenge of running MySQL on Apple Silicon is a textbook example of the complexities involved in CPU architecture transitions. The "no matching manifest" error is not a failure of the software itself, but a mismatch between the requested image's supported architectures and the host's ARM64 hardware. While the initial phase of the M1 release saw a lack of official support, the current state of MySQL 8+ provides native ARM64 images that resolve these issues.

For those tethered to legacy versions, the choice is between the performance penalty of amd64 emulation via the --platform flag or the strategic migration to MariaDB. In a collaborative environment, the use of environment variables within docker-compose.yml provides the necessary flexibility to support a heterogeneous hardware fleet. Ultimately, the move toward multi-architecture manifests and the use of tools like Docker Buildx represents the industry's shift toward a more inclusive and flexible containerization standard, ensuring that high-performance hardware like Apple Silicon can be fully leveraged without architectural bottlenecks.

Sources

1. Choosing the Right Docker Image for your Apple M1 Pro
2. Docker Tip #88: Switching MySQL to MariaDB for ARM 64 (M1) Support
3. Docker MySQL in Macbook Air M1 Help Thread
4. Official MySQL Docker Hub Page