Frequently asked questions (FAQ)

Looking for popular FAQs on Docker Desktop for Mac? Check out the Docker Success Center for knowledge base articles, FAQs, technical support for subscription levels, and more.

Questions about Docker.app

Stable and Edge channels

Q: How do I get the Stable or Edge version of Docker Desktop for Mac?

A: Use the download links for the channels given in the topic Download Docker Desktop for Mac.

This topic also has more information about the two channels.

Q: What is the difference between the Stable and Edge versions of Docker Desktop for Mac?

A: Two different download channels are available for Docker Desktop for Mac:

• The Stable channel provides a general availability release-ready installer for a fully baked and tested, more reliable app. The Stable version of Docker for Mac comes with the latest released version of Docker Engine. The release schedule is synched with Docker Engine releases and hotfixes. On the Stable channel, you can select whether to send usage statistics and other data.

• The Edge channel provides an installer with new features we are working on, but is not necessarily fully tested. It comes with the experimental version of Docker Engine. Bugs, crashes, and issues are more likely to occur with the Edge app, but you get a chance to preview new functionality, experiment, and provide feedback as the apps evolve. Releases are typically more frequent than for Stable, often one or more per month. Usage statistics and crash reports are sent by default. You do not have the option to disable this on the Edge channel.

Q: Can I switch back and forth between Stable and Edge versions of Docker for Mac?

A: Yes, you can switch between versions to try out the Edge releases to see what’s new, then go back to Stable for other work. However, you can have only one app installed at a time. Switching back and forth between Stable and Edge apps can destabilize your development environment, particularly in cases where you switch from a newer (Edge) channel to older (Stable).

For example, containers created with a newer Edge version of Docker for Mac may not work after you switch back to Stable because they may have been created leveraging Edge features that aren’t in Stable yet. Just keep this in mind as you create and work with Edge containers, perhaps in the spirit of a playground space where you are prepared to troubleshoot or start over.

How to save and restore data

The following procedure can be used to save/restore images and container data, for example, if you want to switch between Edge and Stable, or reset your VM disk:

1. Use docker save -o images.tar image1 [image2 ...] to save any images you want to keep. (See save in the Docker Engine command line reference.)

2. Use docker export -o myContainner1.tar container1 to export containers you want to keep. (See export in the Docker Engine command line reference.)

3. Uninstall the current app & Install a different version of the app (Stable or Edge), or reset your VM disk.

4. Use docker load -i images.tar to reload previously saved images. (See load in the Docker Engine

5. Use docker import -i myContainer1.tar to create a filesystem image corresponding to previously exported containers. (See import in the Docker Engine

This procedure explains how to backup and restore data volumes.

What is Docker.app?

Docker.app is Docker for Mac, a bundle of Docker client, and Docker Engine. Docker.app uses the macOS Hypervisor.framework to run containers, meaning that no separate VirtualBox is required.

What are system requirements for Docker for Mac?

You need a Mac that supports hardware virtualization and can run at least macOS 10.11 (macOS El Capitan). See also What to know before you install in the install guide.

Do I need to reinstall Docker for Mac if I change the name of my macOS account?

Starting with Docker for Mac Edge 18.06, this path is relative to the user’s home directory, so it should never be a problem. The remainder of this section is about older releases of Docker for Mac.

If, after installing Docker for Mac, you change the name of your macOS user account and home folder, Docker for Mac fails to start. Reset to Factory Defaults is the simplest fix, but you’ll lose all your settings, containers, images, etc.

To preserve them, open the ~/Library/Group Containers/group.com.docker/settings.json file, and update the diskPath entry.

Do I need to uninstall Docker Toolbox to use Docker for Mac?

No, you can use these side by side. Docker Toolbox leverages a Docker daemon installed using docker-machine in a machine called default. Running eval $(docker-machine env default) in a shell sets DOCKER environment variables locally to connect to the default machine using Engine from Toolbox. To check whether Toolbox DOCKER environment variables are set, run env | grep DOCKER.

To make the client talk to the Docker for Mac Engine, run the command unset ${!DOCKER_*} to unset all DOCKER environment variables in the current shell. (Now, env | grep DOCKER should return no output.) You can have multiple command line shells open, some set to talk to Engine from Toolbox and others set to talk to Docker for Mac. The same applies to docker-compose.

How do I uninstall Docker Toolbox?

You might decide that you do not need Toolbox now that you have Docker for Mac, and want to uninstall it. For details on how to perform a clean uninstall of Toolbox on the Mac, see How to uninstall Toolbox in the Toolbox Mac topics.

Questions about feedback and help

What kind of feedback are we looking for?

Everything is fair game. We’d like your impressions on the download-install process, startup, functionality available, the GUI, usefulness of the app, command line integration, and so on. Tell us about problems, what you like, or functionality you’d like to see added.

We are especially interested in getting feedback on the new swarm mode described in Docker Swarm. A good place to start is the tutorial.

What if I have problems or questions?

You can find the list of frequent issues in Logs and Troubleshooting.

If you do not find a solution in Troubleshooting, browse issues on Docker for Mac issues on GitHub or create a new one. You can also create new issues based on diagnostics. To learn more, see Diagnose problems, send feedback, and create GitHub issues.

Docker for Mac forum provides discussion threads as well, and you can create discussion topics there, but we recommend using the GitHub issues over the forums for better tracking and response.

How can I opt out of sending my usage data?

If you do not want auto-send of usage data, use the Stable channel. For more information, see Stable and Edge channels (“What is the difference between the Stable and Edge versions of Docker for Mac?”).

How is personal data handled in Docker Desktop?

When uploading diagnostics to help Docker with investigating issues, the uploaded diagnostics bundle may contain personal data such as usernames and IP addresses. The diagnostics bundles are only accessible to Docker Inc. employees who are directly involved in diagnosing Docker Desktop issues. By default Docker Inc. will delete uploaded diagnostics bundles after 30 days unless they are referenced in an open issue on the docker/for-mac or docker/for-win issue trackers. If an issue is closed, Docker Inc. will remove the referenced diagnostics bundles within 30 days. You may also request the removal of a diagnostics bundle by either specifying the diagnostics ID or via your GitHub ID (if the diagnostics ID is mentioned in a GitHub issue). Docker Inc. will only use the data in the diagnostics bundle to investigate specific user issues, but may derive high level (non personal) metrics such as the rate of issues from it.

How can I...?

Can I use Docker for Mac with swarm mode?

Yes, you can use Docker for Mac to test single-node features of swarm mode introduced with Docker Engine 1.12, including initializing a swarm with a single node, creating services, and scaling services. Docker “Moby” on Hyperkit serves as the single swarm node. You can also use Docker Machine, which comes with Docker for Mac, to create and experiment a multi-node swarm. Check out the tutorial at Get started with swarm mode.

How do I connect to the remote Docker Engine API?

You might need to provide the location of the Engine API for Docker clients and development tools.

On Docker for Mac, clients can connect to the Docker Engine through a Unix socket: unix:///var/run/docker.sock.

See also Docker Engine API and Docker for Mac forums topic Using pycharm Docker plugin...

If you are working with applications like Apache Maven that expect settings for DOCKER_HOST and DOCKER_CERT_PATH environment variables, specify these to connect to Docker instances through Unix sockets. For example:

export DOCKER_HOST=unix:///var/run/docker.sock

How do I connect from a container to a service on the host?

The Mac has a changing IP address (or none if you have no network access). Our current recommendation is to attach an unused IP to the lo0 interface on the Mac so that containers can connect to this address.

For a full explanation and examples, see I want to connect from a container to a service on the host under Known Limitations, Use Cases, and Workarounds in the Networking topic.

How do I connect to a container from the Mac?

Our current recommendation is to publish a port, or to connect from another container. This is what you need to do even on Linux if the container is on an overlay network, not a bridge network, as these are not routed.

For a full explanation and examples, see I want to connect to a container from the Mac under Known Limitations, Use Cases, and Workarounds in the Networking topic.

How do I add custom CA certificates?

Starting with Docker for Mac Beta 27 and Stable 1.12.3, all trusted certificate authorities (CAs) (root or intermediate) are supported.

For full information on adding server and client side certs, see Add TLS certificates in the Getting Started topic.

How do I add client certificates?

Starting with Docker for Mac 17.06.0-ce, you do not need to push your certificates with git commands anymore. You can put your client certificates in ~/.docker/certs.d/<MyRegistry>:<Port>/client.cert and ~/.docker/certs.d/<MyRegistry>:<Port>/client.key.

For full information on adding server and client side certs, see Add TLS certificates in the Getting Started topic.

Can I pass through a USB device to a container?

Unfortunately it is not possible to pass through a USB device (or a serial port) to a container. For use cases requiring this, we recommend the use of Docker Toolbox.

Disk Usage

What is the disk image?

The containers and images are stored in a disk image named Docker.raw or Docker.qcow2 depending on your settings (see below). By default, the disk image is stored in ~/Library/Containers/com.docker.docker/Data/vms/0.

Qcow2 or Raw?

Starting with High Sierra with Apple Filesystem (APFS) enabled, Docker uses disk images in the “raw” format (Docker.raw), otherwise in the Qcow2 format (Docker.qcow2).

Docker.raw consumes an insane amount of disk space!

This is an illusion. Docker uses the raw format on Macs running the Apple Filesystem (APFS). APFS supports sparse files, which compress long runs of zeroes representing unused space. The output of ls is misleading, because it lists the logical size of the file rather than its physical size. To see the physical size, add the -ks switch; to see the logical size in human readable form, add -lh:

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

In this listing, the logical size is 64GB, but the physical size is only 2.3GB.

Alternatively, you may use du (disk usage):

$ du -h Docker.raw
2,2G	Docker.raw

How do I reduce the size of Docker.qcow2?

If your Docker for Mac uses the Qcow format, the disk image file is Docker.qcow2. This file grows on-demand up to a default maximum file size of 64GiB.

In Docker 1.12 the only way to free space on the host is to delete this file and restart the app. Unfortunately this removes all images and containers.

In Docker 1.13 there is preliminary support for “TRIM” to non-destructively free space on the host. First free space within the Docker.qcow2 by removing unneeded containers and images with the following commands:

• docker ps -a: list all containers
• docker image ls: list all images
• docker system prune: (new in 1.13): deletes all stopped containers, all volumes not used by at least one container, and all images without at least one referring container.

Note the Docker.qcow2 does not shrink in size immediately. In 1.13 a background cron job runs fstrim every 15 minutes. If the space needs to be reclaimed sooner, run this command:

$ docker run --rm -it --privileged --pid=host walkerlee/nsenter -t 1 -m -u -i -n fstrim /var

Once the fstrim has completed, restart the app. When the app shuts down, it compacts the file and free up space. The app takes longer than usual to restart because it must wait for the compaction to complete.

For background conversation thread on this, see Docker.qcow2 never shrinks... on Docker for Mac GitHub issues.

Components of Docker for Mac

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?

It is thinner than VirtualBox and VMWare fusion, and the version we include is tailor made for Docker workloads on the Mac.

Why is com.docker.vmnetd 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.