basecamp/kamal · error · Kamal::Cli::DependencyError

Docker buildx plugin is not installed locally

Error message

Docker buildx plugin is not installed locally

What it means

The same local dependency check as 'Docker is not installed locally', but chosen when the failed message does NOT match /command not found/: the docker binary exists, yet the combined check fails at the buildx stage — meaning the Docker Buildx plugin (needed for multi-platform builds and Kamal's default builder) is missing or broken. Kamal raises Kamal::Cli::DependencyError ('Docker buildx plugin is not installed locally') from ensure_docker_installed before any build runs.

Source

Thrown at lib/kamal/cli/base.rb:319

      def with_env(env)
        current_env = ENV.to_h.dup
        ENV.update(env)
        yield
      ensure
        ENV.clear
        ENV.update(current_env)
      end

      def ensure_docker_installed
        run_locally do
          begin
            execute *KAMAL.builder.ensure_docker_installed
          rescue SSHKit::Command::Failed => e
            error = e.message =~ /command not found/ ?
              "Docker is not installed locally" :
              "Docker buildx plugin is not installed locally"

            raise DependencyError, error
          end
        end
      end
  end
end

View on GitHub (pinned to eee0083b38)

Solutions

1. Install the buildx plugin: download the binary from docker/buildx releases to ~/.docker/cli-plugins/docker-buildx (or /usr/local/lib/docker/cli-plugins) and chmod +x it, then verify `docker buildx version`.
2. Prefer Docker's official repository (docker-ce + docker-buildx-plugin package) over distro packages: `apt-get install docker-buildx-plugin`.
3. If using Docker Desktop, update it — buildx ships bundled. Verify with `docker buildx ls`.
4. Confirm the user running kamal can execute the plugin (permissions on the cli-plugins dir).

Example fix

# before
$ docker buildx version
docker: 'buildx' is not a docker command.
# after
mkdir -p ~/.docker/cli-plugins
curl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-v0.16.3.linux-amd64 \
  -o ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx
docker buildx version   # now succeeds; kamal build proceeds

abort "docker buildx missing" unless system("docker buildx version >/dev/null 2>&1")
system("kamal build")

def buildx_available?
  system("docker buildx version >/dev/null 2>&1")
end

begin
  Kamal::CLI::Build.new.invoke(:push)
rescue Kamal::Cli::DependencyError => e
  raise unless e.message.include?("buildx")
  system("docker buildx install") || raise # then retry build
  retry
end

When it happens

Trigger: Running `kamal build`/`kamal build push` or `kamal registry login` (without --skip-local) where `docker` works but `docker buildx version` fails: buildx plugin never installed (common on minimal docker-ce installs), plugin directory misconfigured, or an old Docker version bundling no buildx.

Common situations: Linux server with docker.io from distro repos (no buildx bundled); Docker installed via snap or a stripped-down package; buildx plugin removed during an upgrade; root-installed plugin not visible to the deploy user.

Related errors

• Docker is not installed locally
• Failed to get endpoint for #{role} on #{host}, did the conta
• Failed to get endpoint for #{role} on #{host}, did the conta
• container not ready after #{KAMAL.config.deploy_timeout} sec
• Missing #{dockerfile}

AI-assisted analysis of basecamp/kamal@eee0083b38 (2026-08-21). Data as JSON: /api/errors/65ae4cdf12d9b299. Report an issue: GitHub.