Back to homepage

Install Colima Stugan

Step-by-step setup for a fresh machine. Colima Stugan needs three things: a Docker engine, Colima (or another Docker daemon manager), and the app itself. This guide walks you through all three on macOS and Linux.

Windows isn't supported yet. WSL2 might work since the Linux .AppImage is x86_64, but it's untested and we don't ship a Windows installer. If you'd like Windows support, open an issue on the repo so we know there's demand.

  1. 1

    Install Homebrew optional

    If you already have Homebrew skip this. Homebrew is the package manager we use to install Colima and the Docker CLI. The one-liner is from brew.sh:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Verify

    Run which brew. You should get a path like /opt/homebrew/bin/brew (Apple Silicon) or /usr/local/bin/brew (Intel).

    Common errors at this step

    • brew: command not found after install

      The Homebrew installer prints a final 'Next steps' block telling you to add brew to your shell's PATH. It's usually two lines you paste into ~/.zprofile. Run them, then open a new terminal.

  2. 2

    Install Colima and the Docker CLI

    Colima manages a small Linux VM that runs the Docker engine. The Docker CLI is what actually sends commands to it. Install both at once:

    brew install colima docker
    This is roughly ~80 MB and takes a minute or two.

    Verify

    colima version and docker --version should both print version numbers.

  3. 3

    Start Colima 

    colima start
    The first run downloads a small Linux VM image (~200 MB), which takes 2-5 minutes on a reasonable connection. Subsequent colima start calls are fast.

    If your machine is comfortable with more headroom, you can tune CPU/memory/disk:

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

    Verify

    docker ps should print a header line (CONTAINER ID IMAGE ...) with no error.

    Common errors at this step

    • limactl not found

      Colima depends on lima; it should have installed as part of brew install colima. Try brew install lima explicitly, then colima start again.

    • error: cannot connect to the Docker daemon

      Colima isn't running. colima status tells you. If status says stopped, colima start. If status says running but Docker still errors, try colima restart.

  4. 4

    Download and install Colima Stugan

    Grab the DMG that matches your Mac from the downloads section: Apple Silicon (M1-M4), Intel, or universal. Open the DMG and drag the app into Applications.
  5. 5

    First launch (Gatekeeper bypass)

    The app is not code-signed yet, so macOS refuses to open it the first time. On macOS 15 (Sequoia) and later: double-click the app, click Done on the warning, then go to System Settings → Privacy & Security, scroll down, and click Open Anyway.

    On older macOS: right-click the app in Applications → Open, which reveals a one-time bypass button.

    You only do this once.
    Common errors at this step

    • Even 'Open Anyway' doesn't work (MDM-managed Mac)

      Some corporate-managed machines block the Gatekeeper bypass UI. Strip the quarantine flag from terminal: xattr -cr /Applications/Colima\ Stugan.app, then open normally.

  6. 6

    Verify it works

    Launch Colima Stugan from Applications. The main dashboard should show your VM as running, and the Containers / Images / Volumes / Networks tabs should be browsable (probably empty if this is a fresh install). The tray icon appears in your menu bar.

    Spin up something to test: docker run --rm -d --name hello nginx. Refresh the Containers tab and 'hello' should appear.
    Common errors at this step

    • App says 'VM not running' even though I started Colima

      Click the 'Start VM' button in the app — it sometimes takes a few seconds for the app to notice the daemon. If that doesn't work: colima stop && colima start in a terminal, then relaunch the app.

Already have Docker Desktop?

It works with Colima Stugan, but don't run Docker Desktop and Colima at the same time — they both want to be the active Docker context. If you want to try Colima alongside Desktop: quit Desktop, run colima start, then launch Colima Stugan.

Still stuck?

Open an issue on the GitHub repo with the exact error message and your OS / version. If you can, include the output of colima status (or docker info if using native Docker on Linux).