Frequently asked questions for Mac

Estimated reading time: 9 minutes

What is Docker.app?

Docker.app is Docker Desktop on Mac. It bundles the Docker client and Docker Engine. Docker.app uses the macOS Hypervisor.framework to run containers.

What is HyperKit?

HyperKit is a hypervisor built on top of the Hypervisor.framework in macOS. It runs entirely in userspace and has no other dependencies.

We use HyperKit to eliminate the need for other VM products, such as Oracle VirtualBox or VMWare Fusion.

What is the benefit of HyperKit?

HyperKit is thinner than VirtualBox and VMWare fusion, and the version included is customized for Docker workloads on Mac.

Why is com.docker.vmnetd still running after I quit the app?

The privileged helper process com.docker.vmnetd is started by launchd and runs in the background. The process does not consume any resources unless Docker.app connects to it, so it’s safe to ignore.

Where does Docker Desktop store Linux containers and images?

Docker Desktop stores Linux containers and images in a single, large “disk image” file in the Mac filesystem. This is different from Docker on Linux, which usually stores containers and images in the /var/lib/docker directory.

Where is the disk image file?

To locate the disk image file, select Preferences from the Docker Dashboard then Advanced from the Resources tab.

The Advanced tab displays the location of the disk image. It also displays the maximum size of the disk image and the actual space the disk image is consuming. Note that other tools might display space usage of the file in terms of the maximum file size, and not the actual file size.

What if the file is too big?

If the disk image file is too big, you can:

  • Move it to a bigger drive
  • Delete unnecessary containers and images
  • Reduce the maximum allowable size of the file
How do I move the file to a bigger drive?

To move the disk image file to a different location:

  1. Select Preferences then Advanced from the Resources tab.

  2. In the Disk image location section, click Browse and choose a new location for the disk image.

  3. Click Apply & Restart for the changes to take effect.

Do not move the file directly in Finder as this can cause Docker Desktop to lose track of the file.

How do I delete unnecessary containers and images?

Check whether you have any unnecessary containers and images. If your client and daemon API are running version 1.25 or later (use the docker version command on the client to check your client and daemon API versions), you can see the detailed space usage information by running:

$ docker system df -v

Alternatively, to list images, run:

$ docker image ls

and then, to list containers, run:

$ docker container ls -a

If there are lots of redundant objects, run the command:

$ docker system prune

This command removes all stopped containers, unused networks, dangling images, and build cache.

It might take a few minutes to reclaim space on the host depending on the format of the disk image file:

  • If the file is named Docker.raw: space on the host should be reclaimed within a few seconds.
  • If the file is named Docker.qcow2: space will be freed by a background process after a few minutes.

Space is only freed when images are deleted. Space is not freed automatically when files are deleted inside running containers. To trigger a space reclamation at any point, run the command:

$ docker run --privileged --pid=host docker/desktop-reclaim-space

Note that many tools report the maximum file size, not the actual file size. To query the actual size of the file on the host from a terminal, run:

$ cd ~/Library/Containers/com.docker.docker/Data/vms/0/data
$ ls -klsh Docker.raw
2333548 -rw-r--r--@ 1 username  staff    64G Dec 13 17:42 Docker.raw

In this example, the actual size of the disk is 2333548 KB, whereas the maximum size of the disk is 64 GB.

How do I reduce the maximum size of the file?

To reduce the maximum size of the disk image file:

  1. Select Preferences then Advanced from the Resources tab.

  2. The Disk image size section contains a slider that allows you to change the maximum size of the disk image. Adjust the slider to set a lower limit.

  3. Click Apply & Restart.

When you reduce the maximum size, the current disk image file is deleted, and therefore, all containers and images will be lost.

How do I add TLS certificates?

You can add trusted Certificate Authorities (CAs) (used to verify registry server certificates) and client certificates (used to authenticate to registries) to your Docker daemon.

Add custom CA certificates (server side)

All trusted CAs (root or intermediate) are supported. Docker Desktop creates a certificate bundle of all user-trusted CAs based on the Mac Keychain, and appends it to Moby trusted certificates. So if an enterprise SSL certificate is trusted by the user on the host, it is trusted by Docker Desktop.

To manually add a custom, self-signed certificate, start by adding the certificate to the macOS keychain, which is picked up by Docker Desktop. Here is an example:

$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt

Or, if you prefer to add the certificate to your own local keychain only (rather than for all users), run this command instead:

$ security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain ca.crt

See also, Directory structures for certificates.

Note: You need to restart Docker Desktop after making any changes to the keychain or to the ~/.docker/certs.d directory in order for the changes to take effect. For a complete explanation of how to do this, see the blog post Adding Self-signed Registry Certs to Docker & Docker Desktop for Mac.

Add client certificates

You can put your client certificates in ~/.docker/certs.d/<MyRegistry>:<Port>/client.cert and ~/.docker/certs.d/<MyRegistry>:<Port>/client.key.

When the Docker Desktop application starts, it copies the ~/.docker/certs.d folder on your Mac to the /etc/docker/certs.d directory on Moby (the Docker Desktop xhyve virtual machine).

  • You need to restart Docker Desktop after making any changes to the keychain or to the ~/.docker/certs.d directory in order for the changes to take effect.

  • The registry cannot be listed as an insecure registry. Docker Desktop ignores certificates listed under insecure registries, and does not send client certificates. Commands like docker run that attempt to pull from the registry produce error messages on the command line, as well as on the registry.

    Directory structures for certificates

If you have this directory structure, you do not need to manually add the CA certificate to your Mac OS system login:

/Users/<user>/.docker/certs.d/
└── <MyRegistry>:<Port>
   ├── ca.crt
   ├── client.cert
   └── client.key

The following further illustrates and explains a configuration with custom certificates:

/etc/docker/certs.d/        <-- Certificate directory
└── localhost:5000          <-- Hostname:port
   ├── client.cert          <-- Client certificate
   ├── client.key           <-- Client key
   └── ca.crt               <-- Certificate authority that signed
                                the registry certificate

You can also have this directory structure, as long as the CA certificate is also in your keychain.

/Users/<user>/.docker/certs.d/
└── <MyRegistry>:<Port>
    ├── client.cert
    └── client.key

To learn more about how to install a CA root certificate for the registry and how to set the client TLS certificate for verification, see Verify repository client with certificates in the Docker Engine topics.

How do I install shell completion?

Docker Desktop comes with scripts to enable completion for the docker and docker-compose commands. The completion scripts may be found inside Docker.app, in the Contents/Resources/etc/ directory and can be installed both in Bash and Zsh.

Bash

Bash has built-in support for completion To activate completion for Docker commands, these files need to be copied or symlinked to your bash_completion.d/ directory. For example, if you installed bash via Homebrew:

etc=/Applications/Docker.app/Contents/Resources/etc
ln -s $etc/docker.bash-completion $(brew --prefix)/etc/bash_completion.d/docker
ln -s $etc/docker-compose.bash-completion $(brew --prefix)/etc/bash_completion.d/docker-compose

Add the following to your ~/.bash_profile:

[ -f /usr/local/etc/bash_completion ] && . /usr/local/etc/bash_completion

OR

if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi

Zsh

In Zsh, the completion system takes care of things. To activate completion for Docker commands, these files need to be copied or symlinked to your Zsh site-functions/ directory. For example, if you installed Zsh via Homebrew:

etc=/Applications/Docker.app/Contents/Resources/etc
ln -s $etc/docker.zsh-completion /usr/local/share/zsh/site-functions/_docker
ln -s $etc/docker-compose.zsh-completion /usr/local/share/zsh/site-functions/_docker-compose

Fish-Shell

Fish-shell also supports tab completion completion system. To activate completion for Docker commands, these files need to be copied or symlinked to your Fish-shell completions/ directory.

Create the completions directory:

$ mkdir -p ~/.config/fish/completions

Now add fish completions from docker.

$ ln -shi /Applications/Docker.app/Contents/Resources/etc/docker.fish-completion ~/.config/fish/completions/docker.fish
$ ln -shi /Applications/Docker.app/Contents/Resources/etc/docker-compose.fish-completion ~/.config/fish/completions/docker-compose.fish
desktop, mac, faqs