DEV Community

Geoffrey Kim
Geoffrey Kim

Posted on • Edited on

110 1 1 1 1

Running Docker on macOS Without Docker Desktop: Alternatives, Limitations, and Best Practices

Docker Desktop is the go-to solution for many macOS users because it bundles everything you need in one package. However, if you prefer not to use Docker Desktop, you can still run Docker on macOS by using alternative tools. In this post, we'll walk you through the process, explain why macOS behaves differently from Linux (like Ubuntu), and highlight some additional considerations.

Why Docker Desktop Is Recommended

The official Docker documentation strongly recommends Docker Desktop for macOS. Here’s why:

  • All-In-One Package: Docker Desktop includes the Docker Engine, Docker CLI, Docker Compose, and the docker-credential-helper in a single installation.
  • Seamless Integration: With Docker Desktop, you don’t have to worry about manually installing or configuring additional components.
  • Official Support: The Docker documentation and support channels primarily focus on Docker Desktop for macOS users.

Running Docker Without Docker Desktop

For those who prefer a lighter setup or want to avoid Docker Desktop for other reasons, you can follow these steps:

1. Install Docker CLI

You can install the Docker CLI using Homebrew. Open your terminal and run:

brew install docker
Enter fullscreen mode Exit fullscreen mode

2. Set Up a Linux Environment with a Lightweight VM

macOS uses the Darwin (BSD-based) kernel, which doesn’t support Docker’s native containerization features (such as namespaces and cgroups) available on Linux. To work around this, you need a Linux virtual machine (VM) running in the background.

One popular tool is Colima, which is easily installed using Homebrew:

brew install colima
Enter fullscreen mode Exit fullscreen mode

Then, start Colima to launch the Linux VM and run the Docker daemon:

colima start
Enter fullscreen mode Exit fullscreen mode

With Colima running, the Docker CLI can communicate with the Docker daemon inside the Linux environment.

3. Run Docker Commands

Now you can execute Docker commands as usual. For example, try running the hello-world image:

docker run hello-world
Enter fullscreen mode Exit fullscreen mode

4. Additional Tools You Might Need

Unlike Docker Desktop, simply installing the Docker CLI and Colima won’t include some additional tools that many users rely on, such as:

  • docker-compose: Used for defining and running multi-container Docker applications.
  • docker-credential-helper: Manages Docker registry credentials.

If you need these tools, install them via Homebrew:

brew install docker-compose docker-credential-helper
Enter fullscreen mode Exit fullscreen mode

Note: Newer versions of Docker Compose may be integrated with Docker Desktop under the command docker compose, but when bypassing Docker Desktop, you might have to install the legacy docker-compose separately.

Why Docker Works Natively on Ubuntu

On Ubuntu (or other Linux distributions), the Docker CLI works seamlessly because:

  • Native Linux Kernel: Ubuntu uses the Linux kernel, which inherently supports containerization via features such as namespaces and control groups (cgroups).
  • Direct Communication: The Docker daemon runs directly on the host system without requiring a virtual machine. As a result, installing the Docker CLI on Ubuntu is sufficient for most use cases.

In essence, Ubuntu’s Linux environment already provides the necessary components for containerization, eliminating the need for a VM or additional setup layers.

What the Official Documentation Says

The official Docker documentation clearly recommends using Docker Desktop on macOS because it delivers a unified experience with all required components bundled together. On macOS, Docker Desktop is the primary supported method since the native OS lacks the Linux kernel features necessary for Docker.

If you choose to bypass Docker Desktop—for instance, by using Colima or similar alternatives—the official documentation implies that you need to manually install the additional tools (like docker-compose and docker-credential-helper). This extra step is essential to achieve the full functionality that Docker Desktop provides out-of-the-box.

Conclusion

While Docker Desktop is the simplest and most integrated way to run Docker on macOS, it isn’t the only option. By installing the Docker CLI and using a lightweight VM tool like Colima, you can create a functional Docker environment on macOS. However, be aware of the following:

  • Kernel Limitations: macOS doesn’t natively support Linux containerization features, which is why a VM-based solution is necessary.
  • Additional Installations: Unlike Docker Desktop, the CLI-only approach won’t automatically provide tools like docker-compose and docker-credential-helper; you must install them separately.
  • Official Guidance: Docker’s official documentation emphasizes Docker Desktop for macOS, so going the alternative route requires extra manual steps.

By understanding these differences and requirements, you can choose the method that best fits your workflow while keeping your setup lean and tailored to your needs.

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

Top comments (3)

Collapse
 
ahmed_azizabbassi_35940c profile image
Ahmed Aziz ABBASSI

Thanks for these easy steps!

Collapse
 
adriyoutomo profile image
Adri

Thank you.

In my case, I need to install docker-compose and docker-credential-helper from homebrew

Collapse
 
mochafreddo profile image
Geoffrey Kim

@adriyoutomo Thank you so much for your valuable feedback! Your comment helped identify an important gap in the original post. I've updated the article to include a dedicated section about additional tools that users might need when running Docker without Docker Desktop on macOS.

The updated post now explicitly mentions that docker-compose and docker-credential-helper need to be installed separately via Homebrew when not using Docker Desktop, along with the exact commands to install them. This should help other users avoid any confusion and get their complete Docker environment set up correctly.

Thanks again for helping make this guide more comprehensive! 🙌

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Dive into an ocean of knowledge with this thought-provoking post, revered deeply within the supportive DEV Community. Developers of all levels are welcome to join and enhance our collective intelligence.

Saying a simple "thank you" can brighten someone's day. Share your gratitude in the comments below!

On DEV, sharing ideas eases our path and fortifies our community connections. Found this helpful? Sending a quick thanks to the author can be profoundly valued.

Okay