Colima Docker Compose

Colima Docker Compose: A Practical Setup Guide for macOS and Linux

Disclosure: This post contains one or more links to providers we have a real, registered affiliate/referral relationship with. We may earn a commission at no extra cost to you if you sign up through them.

Running Colima Docker Compose together gives you a lightweight, Docker Desktop-free way to run containerized applications on macOS (and Linux) without licensing overhead or a heavyweight VM manager. This guide walks through installing Colima, configuring it correctly, and running real Docker Compose stacks against it, along with the quirks you’ll hit around volumes, networking, and resource limits.

Colima (“Container Linux on macOS”) provides a Linux virtual machine with a Docker (or containerd) runtime and exposes a standard Docker socket, which means your existing docker and docker compose CLI commands work unmodified. For teams that dropped Docker Desktop for cost or performance reasons, colima docker compose has become one of the most common replacement patterns, especially for local development and CI runners.

Why Use Colima Docker Compose Instead of Docker Desktop

Docker Desktop bundles a GUI, a licensing model for larger organizations, and its own VM backend. Colima strips that down to just the VM and runtime, driven entirely from the command line. For many engineers, that’s a feature rather than a limitation.

The core reasons teams adopt colima docker compose workflows:

No commercial licensing concerns for organizations above the free-tier employee/revenue thresholds.

Lower background resource usage since there’s no GUI process or auto-update service running.

Full control over VM CPU, memory, and disk allocation via simple flags.

Support for multiple named Colima profiles, so you can run isolated Docker environments side by side.

Works with both the Docker runtime and containerd, depending on your needs.

None of this changes how Docker Compose itself behaves — it changes what’s underneath the Docker socket that Compose talks to.

How Colima Fits Into the Docker Toolchain

Colima doesn’t reimplement Docker. It provisions a Lima-based Linux VM, installs a container runtime inside it, and forwards the Docker socket to your host so the standard docker CLI (and by extension docker compose, part of the Docker CLI plugin ecosystem) can talk to it as if it were local. If you’re already comfortable with the Docker CLI and Compose file format, there’s effectively nothing new to learn about the tool itself — only about the VM layer beneath it.

Installing Colima and Docker Compose

On macOS, the simplest installation path is Homebrew. On Linux, Colima is also available, though it’s less commonly needed there since Docker runs natively.

brew install colima docker docker-compose

This installs three things: the Colima VM manager, the Docker CLI itself (Docker Desktop normally bundles this, so a standalone client is needed), and the docker-compose plugin, which modern Docker CLIs invoke via docker compose (no hyphen).

Start Colima with a basic resource profile:

colima start --cpu 4 --memory 8 --disk 60

Once Colima reports it’s running, verify the Docker socket is reachable:

docker info
docker context ls

You should see a colima context listed and active. If it isn’t the default, switch to it explicitly:

docker context use colima

Choosing a Runtime: Docker vs containerd

Colima supports both the Docker engine and containerd as its underlying runtime. For colima docker compose usage specifically, you want the Docker runtime, since Compose depends on the Docker Engine API:

colima start --runtime docker --cpu 4 --memory 8

If you instead need containerd for Kubernetes-style workloads, Colima can start colima start --kubernetes, but that’s a separate use case from Compose-driven development and worth keeping mentally distinct.

Verifying the Docker Socket Path

A common source of confusion when scripting or configuring IDEs is the actual socket location Colima uses, which differs from Docker Desktop’s default:

docker context inspect colima --format '{{.Endpoints.docker.Host}}'

This typically returns something like unix:///Users/<you>/.colima/default/docker.sock. If any tooling (older Compose plugins, some IDE Docker integrations) hardcodes /var/run/docker.sock, you may need to symlink it or export DOCKER_HOST explicitly:

export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"

Running Docker Compose Stacks on Colima

Once Colima is running and the Docker context is active, Compose behaves exactly as it would with any other Docker backend. There’s no Colima-specific Compose syntax — the compatibility is intentional.

A minimal example, a web service backed by a database:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

Bring it up the normal way:

docker compose up -d
docker compose ps

If you’re setting up a Postgres-backed stack for the first time, the Postgres Docker Compose setup guide covers volume and environment configuration in more depth than this article does. For Redis-based caching layers on the same Colima VM, see the Redis Docker Compose guide.

Debugging a Colima Docker Compose Stack

Because Colima runs Docker inside a Linux VM rather than natively, log and shell access work the same as always through the Docker CLI — there’s no separate “Colima log” abstraction for your containers. Standard debugging commands apply directly:

docker compose logs -f web
docker compose exec web sh

If you’re troubleshooting a stack that won’t start cleanly, the Docker Compose logs debugging guide is a good companion reference, and the Docker Compose down guide is worth reading before you tear a stack down destructively, since down -v also removes named volumes.

Managing Environment Variables and Secrets

Colima itself has no opinion on how you manage .env files or secrets — that’s entirely a Compose-level concern. If your stack references environment files:

docker compose --env-file .env.production up -d

it’s worth reviewing the Docker Compose env guide for the right precedence rules between .env, environment:, and shell exports, and the Docker Compose secrets guide if you’re passing credentials into containers rather than plain environment variables.

Networking and Port Forwarding Considerations

One area where colima docker compose setups differ meaningfully from Docker Desktop is networking. Colima runs containers inside a VM, and by default it uses a specific networking mode for forwarding host ports into that VM.

Things to check when a service is unreachable from the host:

Confirm the port mapping in your ports: block matches what you’re curling on the host.

Check whether Colima was started with --network-address, which assigns the VM a routable IP rather than relying purely on port forwarding — useful for exposing services to other devices on your LAN.

If using host.docker.internal from inside a container to reach the host machine, verify Colima’s version supports it; older releases required a workaround.

For multi-profile setups (colima start --profile myproject), remember each profile has its own isolated Docker context and network namespace.

colima start --network-address
colima list

colima list is useful for confirming which profile is active and what IP address it exposes, which matters most when running Compose stacks that other local services or containers need to reach directly.

Resource Limits and Performance Tuning

Because Colima’s VM has fixed resource allocation, a Docker Compose stack that runs fine on a beefier host can hit memory or CPU ceilings inside the VM even though the host machine has capacity to spare. This is a frequent cause of containers being OOM-killed inside Colima specifically, rather than any fault in the Compose file itself.

Adjust allocation either at start time or by editing the profile config directly:

colima stop
colima start --cpu 6 --memory 12 --disk 100

Alternatively, edit ~/.colima/default/colima.yaml for persistent settings across restarts. If you’re running several Compose stacks concurrently (a database, a message broker, an application layer), size the VM generously enough that container-level mem_limit settings in your Compose file are still meaningful rather than fighting the VM’s own ceiling.

Rebuilding and Iterating on Compose Services

During active development, you’ll frequently need to rebuild images after Dockerfile or dependency changes. This works identically under Colima:

docker compose up --build -d

For a deeper look at cache invalidation and when a full rebuild is actually necessary versus a simple restart, the Docker Compose rebuild guide and the Docker Compose build guide both apply directly, since none of that logic changes under Colima — it’s still standard BuildKit-backed image building, just executed inside the Colima VM instead of Docker Desktop’s VM.

If you’re deciding between a single Dockerfile-driven container and a full Compose stack for a small project, the Dockerfile vs Docker Compose comparison is a useful starting point regardless of which backend runs the containers.

Running Colima Docker Compose in CI or on a Remote Server

Colima isn’t limited to local laptops. It’s increasingly used on CI runners and even remote Linux servers as a lightweight way to get a consistent Docker environment without depending on the host’s native Docker installation or system-level Docker daemon configuration.

A typical pattern for a CI job:

colima start --cpu 2 --memory 4
docker compose -f docker-compose.ci.yml up --abort-on-container-exit

The --abort-on-container-exit flag is particularly useful in CI, since it stops the whole stack as soon as your test-runner container exits, propagating its exit code back to the CI job.

If you’re hosting the Colima VM itself on a VPS rather than a laptop, review your unmanaged VPS hosting guide considerations first — Colima still needs adequate CPU/memory headroom, and a minimally provisioned VPS can bottleneck a Compose stack the same way a small local VM allocation would. For providers with straightforward resource scaling, DigitalOcean and Vultr are common choices for this kind of workload.

Common Problems and How to Resolve Them

Most colima docker compose issues fall into a small number of categories: stale VM state, socket path mismatches, and resource exhaustion.

Compose can’t find the Docker daemon — usually means the colima context isn’t active, or DOCKER_HOST is pointing at a stale socket path from a previous VM instance.

Containers exit immediately with no logs — check colima status first; sometimes the VM itself has silently stopped rather than the container failing.

Volumes not persisting data between restarts — confirm you’re using named volumes (volumes: top-level key) rather than assuming bind-mount behavior identical to a native Linux host, since path translation between macOS host paths and the Linux VM can behave differently than expected.

Slow file I/O on bind mounts — this is a known characteristic of VM-based Docker on macOS generally (not unique to Colima), and is usually mitigated by using named volumes for anything write-heavy, like database data directories.

Resetting a broken Colima VM cleanly, without touching your Compose files or images defined elsewhere, is often faster than debugging a corrupted VM state:

colima delete
colima start --cpu 4 --memory 8

Note that colima delete removes the VM and everything inside it, including any data stored only inside VM-local volumes — always confirm backups or reproducibility of that data before running it.

Conclusion

Colima docker compose setups give you a genuinely drop-in replacement for Docker Desktop’s Compose workflow, with the tradeoff that you now own a bit more of the VM-layer configuration yourself — resource allocation, networking mode, and socket paths in particular. Once those are set correctly, day-to-day Compose usage (up, down, logs, exec, rebuilds) is identical to any other Docker backend, which is exactly why the migration path tends to be low-friction for teams making the switch. Start with conservative CPU/memory settings, verify the Docker context and socket path early, and treat Colima’s VM lifecycle (start, stop, delete) as a separate layer from your actual Compose stack management.

For further reference on the underlying VM and container runtime concepts Colima relies on, see the official Docker documentation and, if you later move toward orchestrated multi-node deployments, the Kubernetes documentation — though for most local development and CI use cases, Compose on Colima is sufficient without introducing that complexity.

Recommended: Ready to put this into practice? DigitalOcean is a tool we use for exactly this, and we have a real, disclosed affiliate relationship with them.

FAQ

Does Colima support Docker Compose out of the box?
Yes. Colima exposes a standard Docker socket, and once you install the docker-compose CLI plugin (or a Docker CLI version that bundles it), docker compose commands work exactly as they would against Docker Desktop or a native Linux Docker install.

Is Colima a replacement for Docker Desktop?
For most command-line-driven workflows, yes. Colima doesn’t provide a GUI or Docker Desktop’s built-in dashboard, but the Docker Engine, CLI, and Compose functionality behind it are equivalent for running colima docker compose stacks.

Why can’t my container reach a service running on my Mac host?
This is usually a networking-mode issue. Check whether host.docker.internal resolves correctly inside the container, and confirm you’re using a Colima version and network configuration that supports host-to-VM communication as expected.

Can I run multiple isolated Colima Docker Compose environments at once?
Yes, using Colima’s profile feature (colima start --profile <name>). Each profile gets its own VM, Docker context, and network namespace, so you can run separate Compose stacks in isolation without them interfering with each other.