Solution - Fix Docker Buildx Plugin for Apple Silicon by Symlink Creation

When installing/using Docker Buildx on Apple Silicon macs, an issue occurs for arm64 macOS.

The solution involves creating a symlink to your Docker CLI plugins directory using a shell script shown below.

Short answer

Run this script:

#!/bin/bash

# Check if /usr/local/lib/docker directory exists, create it if it doesn't
if [ ! -d "/usr/local/lib/docker" ]; then
  echo "Directory /usr/local/lib/docker does not exist. Creating..."
  mkdir -p /usr/local/lib/docker
  echo "Created directory: /usr/local/lib/docker"
else
  echo "Directory /usr/local/lib/docker already exists."
fi

# Check for Docker CLI plugins directory under /usr/local/lib
if [ -d "/usr/local/lib/docker/cli-plugins" ]; then
  echo "Docker CLI plugins directory already exists: /usr/local/lib/docker/cli-plugins"
else
  # Create symlink to Docker CLI plugins directory under /Applications
  echo "Docker CLI plugins directory does not exist. Creating symlink..."
  ln -s /Applications/Docker.app/Contents/Resources/cli-plugins /usr/local/lib/docker/cli-plugins
  echo "Symlink created: /usr/local/lib/docker/cli-plugins -> /Applications/Docker.app/Contents/Resources/cli-plugins"
fi

# Verify the symlink
if [ -L "/usr/local/lib/docker/cli-plugins" ]; then
  echo "Symlink verification: Successful"
else
  echo "Symlink verification: Failed"
fi

Long Answer

Expected Behavior

The ability to install Docker Buildx on your Apple Silicon M1/M2/M3/M4 MacBook/Mac with MacOS to build x86 Docker images.
Being able to run docker buildx version command with legitimate output.
No exceptions when using buildx, behavior is consistent across both architectures, arm64 or x86_64.
Ability to conduct multi-arch builds e.g. docker buildx build --platform linux/amd64,linux/arm64 .

Actual Behavior

Error message docker: 'buildx' is not a docker command. despite having installed buildx plugin.
Inconsistent behavior with exceptions when using buildx.

Pre-requisites

The following MacOS software must be installed prior to applying this fix.

Docker (ideally along with Docker Desktop app turned on)
Docker-Buildx plugin

Docker-Buildx plugin Installation

As of February 2025, Installation command docker buildx install is referenced in official documentation but it does not work, it has been removed from reference documentation anyway, use brew installation instead.

Steps to Reproduce and Fix

Verify if the /usr/local/lib/docker directory exists.
If the directory does not exist, create it.
Check if Docker CLI plugins directory exists under /usr/local/lib.
If the Docker CLI plugins directory does not exist, create a symlink to the Docker CLI plugins directory under /Applications.
Verify the symlink creation.

Script I used

Same as above, but without additional echo statements.

#!/bin/bash

# Check if /usr/local/lib/docker directory exists, create it if it doesn't
if [ ! -d "/usr/local/lib/docker" ]; then
  mkdir -p /usr/local/lib/docker
  echo "Created directory: /usr/local/lib/docker"
fi

# Check for Docker CLI plugins directory under /usr/local/lib
if [ -d "/usr/local/lib/docker/cli-plugins" ]; then
  echo "Docker CLI plugins directory already exists."
else
  # Create symlink to Docker CLI plugins directory under /Applications
  ln -s /Applications/Docker.app/Contents/Resources/cli-plugins /usr/local/lib/docker/cli-plugins
  echo "Symlink created: /usr/local/lib/docker/cli-plugins -> /Applications/Docker.app/Contents/Resources/cli-plugins"
fi

# Verify the symlink
if [ -L "/usr/local/lib/docker/cli-plugins" ]; then
  echo "Symlink verification: Successful"
else
  echo "Symlink verification: Failed"
fi

Additional Configuration

Before applying the symlink fix, you may need to edit the ~/.docker/daemon.json configuration file was edited as follows:

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "features": {
    "buildkit": true
  }
}

Note: I wouldn't rule out having "experimental": true, depending on what version of docker you have installed.

My personal config

For your curiosity, I use an M2 Macbook (MacOS Sequoia 15.2) with both docker and docker-buildx installed via brew.

I had my ~/.docker/config.json configured as:

{
    "auths": "{HIDDENCONFIGURATION}",
    "credsStore": "*****",
    "credHelpers": "{HIDDENCONFIGURATION}",
    "experimental": "enabled",
    "currentContext": "desktop-linux",
    "cliPluginsExtraDirs": [
        "/opt/homebrew/lib/docker/cli-plugins"
    ],
    "plugins": {
        "-x-cli-hints": {
            "enabled": "true"
        },
        "debug": {
            "hooks": "exec"
        },
        "scout": {
            "hooks": "pull,buildx build"
        }
    }
}

Brew docker-buildx information

aeonitis@Mac scripts % brew info docker-buildx
==> docker-buildx: stable 0.21.1 (bottled), HEAD
Docker CLI plugin for extended build capabilities with BuildKit
https://docs.docker.com/buildx/working-with-buildx/
Installed
/opt/homebrew/Cellar/docker-buildx/0.21.1 (37 files, 63.8MB) *
  Poured from bottle using the formulae.brew.sh API on 2025-02-24 at 18:44:26
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/d/docker-buildx.rb
License: Apache-2.0
==> Dependencies
Build: go ✔
==> Options
--HEAD
	Install HEAD version
==> Caveats
docker-buildx is a Docker plugin. For Docker to find the plugin, add "cliPluginsExtraDirs" to ~/.docker/config.json:
  "cliPluginsExtraDirs": [
      "/opt/homebrew/lib/docker/cli-plugins"
  ]

zsh completions have been installed to:
  /opt/homebrew/share/zsh/site-functions
==> Analytics
install: 5,307 (30 days), 16,180 (90 days), 49,246 (365 days)
install-on-request: 5,299 (30 days), 16,162 (90 days), 49,181 (365 days)
build-error: 0 (30 days)

Brew Docker information

aeonitis@Mac scripts % brew info docker
Warning: Treating docker as a formula. For the cask, use homebrew/cask/docker or specify the `--cask` flag. To silence this message, use the `--formula` flag.
==> docker: stable 28.0.0 (bottled), HEAD
Pack, ship and run any application as a lightweight container
https://www.docker.com/
Installed
/opt/homebrew/Cellar/docker/28.0.0 (13 files, 26.7MB)
  Poured from bottle using the formulae.brew.sh API on 2025-02-21 at 23:04:41
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/d/docker.rb
License: Apache-2.0
==> Dependencies
Build: go ✔, go-md2man ✘
Required: docker-completion ✔
==> Options
--HEAD
	Install HEAD version
==> Analytics
install: 49,324 (30 days), 140,326 (90 days), 521,171 (365 days)
install-on-request: 49,116 (30 days), 139,878 (90 days), 519,532 (365 days)
build-error: 3 (30 days)

Verification

To verify the plugin presence:

aeonitis@Mac scripts % ls ~/.docker/cli-plugins
docker-buildx ...

To verify the solution, you can run the following commands:

docker buildx version
docker buildx ls

Sample output

aeonitis@Mac scripts % docker buildx version
github.com/docker/buildx v0.21.1 7c2359c6bf8b3331413c0fe95918fe1cfe9aa127

aeonitis@Mac scripts % docker buildx ls
NAME/NODE     DRIVER/ENDPOINT   STATUS    BUILDKIT   PLATFORMS
default*      docker
 \_ default    \_ default       running   v0.18.2    linux/amd64 (+2), linux/arm64, linux/arm (+2), linux/ppc64le, (6 more)

Note: The docker buildx version command did not work before the symlink fix.

Tested on Version

aeonitis@Mac scripts % docker version
Client:
 Version:           27.5.1
 API version:       1.47
 Go version:        go1.22.11
 Git commit:        9f9e405
 Built:             Wed Jan 22 13:37:19 2025
 OS/Arch:           darwin/arm64
 Context:           default

Server: Docker Desktop 4.38.0 (181591)
 Engine:
  Version:          27.5.1
  API version:      1.47 (minimum version 1.24)
  Go version:       go1.22.11
  Git commit:       4c9b3b0
  Built:            Wed Jan 22 13:41:25 2025
  OS/Arch:          linux/arm64
  Experimental:     false
 containerd:
  Version:          1.7.25
  GitCommit:        bcc810d6b9066471b0b6fa75f557a15a1cbf31bb
 runc:
  Version:          1.1.12
  GitCommit:        v1.1.12-0-g51d5e946
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Thank you, please share your config differences, comment here or on official github issues below and if it's worked for you.

References

Yet to confirm

Is end goal to have native macOS directory ~/.docker/cli-plugins working soon, or is there a reason to remain with path~/.docker/cli-plugins/docker-buildx. I wonder if a dedicated macOS specific config which isn't "currentContext": "desktop-linux" is in progress...

Aeonitis/DockerBuildxArm64MacOSFix.md