Docker MySQL on Apple Silicon M1/M2

When using Docker on Apple Silicon (M1/M2) Macs, you may encounter the error "no matching manifest for linux/arm64/v8 in the manifest list entries" when trying to run MySQL containers. This error occurs because MySQL and some other database images don't natively support the ARM64 architecture used by Apple Silicon chips.

Problem Overview

The core issue is architectural incompatibility. Apple Silicon Macs use ARM64 (aarch64) architecture, while many Docker images—including official MySQL images—are built for x86_64 (amd64) architecture. When Docker can't find an ARM64-compatible version of an image, it throws the manifest error.

Solutions

Quick Fix: Platform Specification

The most straightforward solution is to explicitly specify the platform in your Docker configuration:

# docker-compose.yml
services:
  db:
    image: mysql:5.7
    platform: linux/amd64  # Force x86_64 architecture
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: mydb
    ports:
      - "3306:3306"

For individual docker run commands:

docker run --platform linux/amd64 --name mysql-container -e MYSQL_ROOT_PASSWORD=password -d mysql:5.7

Performance Consideration

Using x86_64 images on ARM64 architecture requires emulation, which may result in reduced performance and higher memory usage compared to native ARM64 images.

Alternative: MySQL Server Image

Oracle provides an official MySQL Server image that supports ARM64:

# docker-compose.yml
services:
  db:
    image: mysql/mysql-server:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: mydb
      MYSQL_ROOT_HOST: "%"
    ports:
      - "3306:3306"

Alternative: MariaDB

Consider using MariaDB as a drop-in replacement for MySQL with native ARM64 support:

# docker-compose.yml
services:
  db:
    image: mariadb:10.6
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: mydb
    ports:
      - "3306:3306"

Advanced Configuration

Team Development Solution

For teams with mixed architectures, create a platform-specific override file:

# docker-compose.mac.yml
version: '3'
services:
  mysql:
    platform: linux/amd64

Then run with both configuration files:

docker-compose -f docker-compose.yml -f docker-compose.mac.yml up

Environment Variable Solution

Set a default platform for all Docker commands:

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export DOCKER_DEFAULT_PLATFORM=linux/amd64

# Apply the change
source ~/.zshrc

Dockerfile Modification

If building custom images, specify the platform in your Dockerfile:

FROM --platform=linux/amd64 mysql:5.7
# Rest of your Dockerfile...

Performance Optimization

TIP

For better performance on Apple Silicon:

1. Use ARM64-native images when available
2. Keep Docker Desktop updated to the latest version
3. Allocate sufficient resources to Docker in Preferences > Resources

Known Limitations

When using x86_64 images on ARM64, you may encounter:

• Reduced I/O performance due to emulation
• Lack of Linux Native AIO support for MySQL
• Increased memory usage
• Potential compatibility issues with某些 native extensions

Conclusion

While Apple Silicon support in the Docker ecosystem continues to improve, the platform specification approach provides a reliable workaround for running MySQL and other x86_64-only images. For production workloads on Apple Silicon, consider using ARM64-native database images like MariaDB or the official MySQL Server image from Oracle.

As the Docker ecosystem evolves, more images will likely add native ARM64 support, eventually making these workarounds unnecessary.