> ## Documentation Index > Fetch the complete content index at: https://smallsharpsoftwaretools.com/llms.txt > Use this file to discover all available pages before exploring further. # Use Colima to Run Docker Containers on macOS The official Docker for Mac application is subject to some licensing terms that may not work for some people or organizations, and some users have reported issues with forced updates that disrupt their workflows. If you need to run containers on your Mac, [Colima](https://github.com/abiosoft/colima) is an open source container runtime with minimal setup that works on macOS and Linux. In this tutorial you'll install Colima and Docker's command-line tools with [Homebrew](https://smallsharpsoftwaretools.com/tutorials/homebrew/). Then you'll manage your images and containers. ## What You Need To complete this tutorial, you'll need Homebrew installed, which you can do by following the [Install Homebrew]({{< ref "homebrew" >}}) tutorial. ## Uninstalling Docker for Mac Before moving forward, you'll want to remove the existing Docker for Mac application if you have it running. Unfortunately, this process removes all your containers as well as your images. You'll have to rebuild your local images and re-download any upstream images again. To uninstall Docker for Mac, right-click on the Docker icon in your task bar, select **Troubleshooting**, and then select **Uninstall**. This process warns you that it will remove all your containers and images, and will then perform the uninstall process. At the end, the Docker for Mac application will exit. Once it's completed, you can install Colima. ## Installing Colima and Docker's CLI with Homebrew The fastest way to get Colima installed is through Homebrew. ```command brew install colima ``` Once Colima installs, install Docker and Docker Compose. ```command brew install docker docker-compose ``` Then configure `docker-compose` as a Docker plugin so you can use `docker compose` as a command instead of the legacy `docker-compose` script. First, create a folder in your home directory to hold Docker CLI plugins: ```command mkdir -p ~/.docker/cli-plugins ``` Then symlink the `docker-compose` command into that new folder: ```command ln -sfn $(brew --prefix)/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose ``` Run `docker compose`: ```command docker compose ``` Ensure you see the help message that looks like the following output: ```output Usage: docker compose [OPTIONS] COMMAND Docker Compose Options: --ansi string Control when to print ANSI control characters ("never"|"always"|"auto") (default "auto") --compatibility Run compose in backward compatibility mode --env-file string Specify an alternate environment file. ... version Show the Docker Compose version information Run 'docker compose COMMAND --help' for more information on a command. ``` You'll also need [Buildx](https://docs.docker.com/build/architecture/#buildx) to build some Docker containers. Install this with Homebrew: ```command brew install docker-Buildx ``` Once downloaded, symlink it to the `cli-plugins` folder: ```command ln -sfn $(brew --prefix)/opt/docker-buildx/bin/docker-buildx ~/.docker/cli-plugins/docker-buildx ``` With the commands installed, you can start Colima and work with containers ## Using Colima to Run Images You installed `colima`, but it isn't running yet. Colima works by using a virtual machine to run containers, which is similar to how Docker for Mac works. On the first run, Colima downloads and configures a virtual machine to run the containers. This virtual machine has 2 CPUs, 2GiB memory and 60GiB storage, which is enough for moderate use. You can change the memory size and number of virtual CPUs at any time. Start Colima with the following command: ```command colima start ``` You'll see the following output as Colima downloads the virtual machine: ```output INFO[0000] starting colima INFO[0000] creating and starting ... context=vm > msg="Terminal is not available, proceeding without opening an editor" > msg="Attempting to download the image from \"https://github.com/abiosoft/alpine-lima/releases/download/colima-v0.3.4-1/alpine-lima-clm-3.14.3-x86_64.iso\"" \ ``` Once Colima downloads the virtual machine it'll disconnect and reconnect and you'll be ready to start using it: ```output INFO[0000] starting colima INFO[0000] creating and starting ... context=vm INFO[0041] provisioning ... context=docker INFO[0041] restarting VM to complete setup ... context=docker INFO[0041] stopping ... context=vm INFO[0048] starting ... context=vm INFO[0068] starting ... context=docker INFO[0073] waiting for startup to complete ... context=docker INFO[0074] done ``` With Colima running, run Docker's [hello-world](https://hub.docker.com/_/hello-world) image, which is a quick way to verify that your Docker runtime works: ```command docker run hello-world ``` You'll see the following output which shows that the `hello-world` image wasn't found locally, so Docker needs to download it. It then runs and exits: ```output Unable to find image 'hello-world:latest' locally latest: Pulling from library/hello-world 2db29710123e: Pull complete Digest: sha256:bfea6278a0a267fad2634554f4f0c6f31981eea41c553fdf5a83e95a41d40c38 Status: Downloaded newer image for hello-world:latest Hello from Docker! This message shows that your installation appears to be working correctly. To generate this message, Docker took the following steps: 1. The Docker client contacted the Docker daemon. 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (amd64) 3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading. 4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal. To try something more ambitious, you can run an Ubuntu container with: $ docker run -it ubuntu bash Share images, automate workflows, and more with a free Docker ID: https://hub.docker.com/ For more examples and ideas, visit: ``` Use the `docker ps -a` command to see the stopped container: ```command docker ps -a ``` You can see the container and image displayed in the output: ```output CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES a8fb0e8a2e32 hello-world "/hello" 2 minutes ago Exited (0) 2 minutes ago amazing_antonelli ``` Use `docker rm` to remove the container by using its name or container ID. In this case, the name is `amazing_antonelli`. Yours will be different: ```command docker rm amazing_antonelli ``` Now use `docker images` to view the images installed: ```command docker images ``` You see the `hello-world` image listed: ``` REPOSITORY TAG IMAGE ID CREATED SIZE hello-world latest feb5d9fea6a5 6 months ago 13.3kB ``` Use the `docker rmi` command to remove the image using its image ID. Your image ID will be different: ```command docker rmi feb5d9fea6a5 ``` Now that you can manage images, it's time to build your own. ## Building Your Own Image You can run pre-built images on Colima, so the next step is to try to use Docker to build your own images. To test this out, you'll create a `Docker ` and create your own container image that runs a custom HTML file inside of nginx. Create a new project folder called `docker-test` and switch to that folder: ```command mkdir docker-test && cd docker-test ``` Create a new folder to hold your HTML file: ```command mkdir html ``` Create a new HTML file in that folder. ```command cat < html/index.html

Hi from Docker

EOF ``` Then create a new file called `Dockerfile` that uses the `nginx:latest` image and copies your HTML files into the `/usr/share/nginx/html` folder where nginx looks for them: ```command cat < Dockerfile FROM nginx:latest COPY ./html /usr/share/nginx/html EOF ``` Build the image and call it `docker-nginx-test`: ```command docker build -t docker-nginx-test . ``` The image builds: ```output [+] Building 0.9s (7/7) FINISHED => [internal] load build definition from Dockerfile 0.0s => => transferring dockerfile: 94B 0.0s ,,, => exporting to image 0.0s => => exporting layers 0.0s => => writing image sha256:04f227cdc8d163456a2b10fb4d91e56a4b158bae68b5232b431008a475c88c60 0.0s => => naming to docker.io/library/docker-nginx-test 0.0s ``` View the image: ```command docker images ``` You see your new image in the list: ```output REPOSITORY TAG IMAGE ID CREATED SIZE docker-nginx-test latest 04f227cdc8d1 6 minutes ago 142MB ``` Run your image with terminal support and set it to destroy the container when you quit: ```command docker run --rm -t -p 3000:80 docker-nginx-test ``` Visit `http://localhost:3000` in your browser and you'll see the "Hello from Docker" message. Back in your terminal, press `CTRL+C` to stop the container. The container stops and Docker removes the container. Now that you know the basics are working, you can start using Colima with the rest of your Docker workflow. Before wrapping up, take a look at how to customize the virtual machine settings. ## Customizing Colima's Virtual Machine You can control the memory, CPUs, and disk space the virtual machine uses, and you can specify whether or not you want Kubernetes support. You can change the CPUs and memory on an exiting machine by stopping the machine and starting it again with new options. To use 4 CPUs and 4GiB of memory with your existing machine, stop the machine and restart it, passing the `--cpu` and `--memory` options: ```command colima stop ``` ```command colima start --cpu 4 --memory 4 ``` If you need more disk space, you have to create a new virtual machine. Unfortunately you can't resize the virtual machine's disk. To create a VM with four CPUs, 4 GB of memory, and 100GiB of disk space, start Colima with the following options: ```command colima start --cpu 4 --memory 4 --disk 100 ``` Finally, if you need Kubernetes support, you can start the VM with the `--with-kubernetes` support. You'll need `kubectl` installed, which you can do through Homebrew with `brew install kubectl`. Review all the available startup options with `colima help start`. ## Conclusion Colima provides a free and open container runtime you can use instead of the official Docker for Mac client. It's lightweight, installs quickly, and has many of the same options the official client has, without some of the drawbacks. Learn more on [Colima's GitHub page](https://github.com/abiosoft/colima), or by exploring `colima help`.