CodeNote.net

How to Install Docker Desktop on an Existing Docker CLI Environment (macOS Homebrew)

#docker #macos #homebrew
Tadashi Shigeoka ·  Wed, January 14, 2026

This guide explains how to install Docker Desktop on a macOS environment where only Docker CLI was installed via Homebrew.

Prerequisites

  • macOS (Intel Mac / Apple Silicon supported)
  • Homebrew installed
  • Docker CLI installed via Homebrew (brew install docker)

Background

As introduced in Colima + Docker CLI Setup Guide (macOS), many developers use Docker CLI + Colima without Docker Desktop.

However, there are cases where you may want to switch to Docker Desktop later, such as when team policies change or when you need Docker Desktop’s GUI features.

Common Question

When installing Docker Desktop on an environment with only Docker CLI installed, you might have the following question:

Docker CLI を先に削除したほうが良いですか？

(Should I uninstall Docker CLI first?)

The short answer is no, you don’t need to uninstall it first. However, you’ll need a small workaround during installation.

If You Want to Uninstall First

If you prefer to uninstall Docker CLI related packages first, you can use the following commands:

brew uninstall docker
brew uninstall docker-compose   # if installed
brew uninstall docker-buildx    # if installed

Then install Docker Desktop:

brew install --cask docker-desktop

This method avoids any conflicts.

Installing Without Uninstalling First

If you try to install Docker Desktop without uninstalling Docker CLI, you may encounter the following error.

The Error

brew install --cask docker-desktop
==> Downloading https://desktop.docker.com/mac/main/arm64/214940/Docker.dmg
Already downloaded: /Users/your_name/Library/Caches/Homebrew/downloads/081a17783363af6e0cf6d48d362aae02095f9fc
5d6dfd90e746912cfefd2d579--Docker.dmg
==> Installing Cask docker-desktop
==> Moving App 'Docker.app' to '/Applications/Docker.app'
==> Backing App 'Docker.app' up to '/opt/homebrew/Caskroom/docker-desktop/4.56.0,214940/Docker.app'
==> Removing App '/Applications/Docker.app'
==> Purging files for version 4.56.0,214940 of Cask docker-desktop
Error: It seems there is already a Bash Completion at '/opt/homebrew/etc/bash_completion.d/docker-compose'.

Cause of the Error

This error occurs because the docker (Docker CLI) and docker-compose packages installed via Homebrew have installed shell completion files.

Docker Desktop also tries to install completion files to the same location, causing a conflict.

Solution

Use the --force option to install:

brew install --cask docker-desktop --force

With the --force option, you can overwrite existing completion files and install Docker Desktop.

About the —force Option

The --force option performs the following actions:

  • Overwrites existing files and continues installation
  • Removes previously installed files and reinstalls

The completion files will be replaced with those from Docker Desktop, but they are functionally equivalent, so there’s no issue.

Verifying the Installation

After installing Docker Desktop, verify that it works correctly.

Launch Docker Desktop

open /Applications/Docker.app

Alternatively, launch Docker.app from the Applications folder, or search for “Docker” in Spotlight.

Verify Docker CLI

docker --version
docker run hello-world

If you see the “Hello from Docker!” message, everything is working correctly.

Summary

When installing Docker Desktop on an environment where only Docker CLI was installed via Homebrew, you can resolve completion file conflicts by using the --force option.

brew install --cask docker-desktop --force
  • No need to uninstall first - Use --force option to overwrite
  • Completion file conflict - Bash Completion files are the cause

That’s all from the Gemba.

References