Command-Line Docker Setup for macOS (without Docker Desktop)
This document outlines the steps to set up a complete Docker environment on macOS using only command-line tools. This provides an alternative to the paid Docker Desktop application, which is ideal for users who primarily interact with Docker through the terminal.
This setup uses Colima, a lightweight, open-source tool that provides container runtimes on macOS.
Prerequisites
- Homebrew package manager installed on your macOS.
Setup Process
The following steps will guide you through the installation and configuration of Colima and the necessary Docker tools.
1. Install Colima and Docker Tools
First, we install Colima, the Docker command-line interface (CLI), and Docker Compose using Homebrew.
brew install colima docker docker-compose
2. Start the Colima Virtual Machine
Colima runs the Docker engine inside a lightweight Linux virtual machine. Start the Colima VM with the following command. The first time you run this, it will download the necessary components and create the virtual machine.
colima start
3. Configure the Docker Context
By default, your Docker CLI might still be configured to look for a Docker Desktop installation. We need to tell it to use the engine provided by Colima. Docker manages this through "contexts".
Switch the active context to colima:
docker context use colima
4. Configure the Docker Compose Plugin
To ensure the docker-compose command works correctly as a Docker plugin, you need to update the Docker configuration file.
This command will create the ~/.docker/config.json file (if it doesn’t exist) and add the necessary setting.
mkdir -p ~/.docker && echo '{
"cliPluginsExtraDirs": [
"/opt/homebrew/lib/docker/cli-plugins"
]
}' > ~/.docker/config.json
Verification
To confirm that your setup is working correctly, run the hello-world container. This will download a small test image from Docker Hub and run it.
docker run hello-world
You should see a "Hello from Docker!" message, which confirms your environment is ready.
Daily Usage
Starting the Docker Environment
The Colima VM does not start automatically. When you want to use Docker, run:
colima start
Stopping the Docker Environment
When you are finished using Docker, you can stop the Colima VM to free up system resources:
colima stop
Uninstalling Docker Desktop
Once you have confirmed your Colima setup is working, you can remove the Docker Desktop application to free up space and avoid confusion.
Note: This command requires administrator privileges. You will need to run it in your own terminal and enter your password when prompted.
brew uninstall --cask docker
Troubleshooting
docker: command not found after uninstalling Docker Desktop
Uninstalling the Docker Desktop application can sometimes remove the docker command-line tool itself. If you see a "command not found" error, you can easily restore it.
Since the Docker CLI was also installed via Homebrew, you can re-link the formula to make the command available again:
brew link docker
After running this, the docker command should work correctly.
