If you already have an installation of Docker Toolbox, read these topicsfirst to learn how Docker Desktop on Mac and Docker Toolbox differ, and how they cancoexist.

Logs and troubleshooting Estimated reading time: 21 minutes This page contains information on how to diagnose and troubleshoot problems, send logs and communicate with the Docker Desktop team, use our forums and Knowledge Hub, browse and log issues on GitHub,. Error Checking Tls Connection Could Not Find Matching Ip For Mac. An IP address, but Docker Machine could not reach it successfully.

The Docker Toolbox environment

Docker Toolbox installs docker, docker-compose, and docker-machine in/usr/local/bin on your Mac. It also installs VirtualBox. At installation time,Toolbox uses docker-machine to provision a VirtualBox VM called default,running the boot2docker Linux distribution, with Docker Enginewith certificates located on your Mac at$HOME/.docker/machine/machines/default.

Before you use docker or docker-compose on your Mac, you typically use thecommand eval $(docker-machine env default) to set environment variables sothat docker or docker-compose know how to talk to Docker Engine running onVirtualBox.

This setup is shown in the following diagram.

The Docker Desktop on Mac environment

Docker Desktop on Mac is a Mac-native application, that you install in /Applications.At installation time, it creates symlinks in /usr/local/bin for docker anddocker-compose and others, to the commands in the applicationbundle, in /Applications/Docker.app/Contents/Resources/bin.

Here are some key points to know about Docker Desktop on Mac before you get started:

• Docker Desktop uses HyperKit instead of Virtual Box. Hyperkit is a lightweight macOS virtualization solution built on top of Hypervisor.framework in macOS 10.10 Yosemite and higher.

• When you install Docker Desktop on Mac, machines created with Docker Machine are not affected.

• Docker Desktop does not use docker-machine to provision its VM.The Docker Engine API is exposed on asocket available to the Mac host at /var/run/docker.sock. This is thedefault location Docker and Docker Compose clients use to connect tothe Docker daemon, so you can use docker and docker-compose CLI commandson your Mac.

This setup is shown in the following diagram.

With Docker Desktop on Mac, you only get (and only usually need) one VM, managed by Docker Desktop. Docker Desktop automatically upgrades the Docker client and daemon when updates are available.

Also note that Docker Desktop can’t route traffic to containers, so you can’tdirectly access an exposed port on a running container from the hosting machine.

If you do need multiple VMs, such as when testing multi-node swarms, you cancontinue to use Docker Machine, which operates outside the scope of Docker Desktop. See Docker Toolbox and Docker Desktopcoexistence.

Setting up to run Docker Desktop on Mac

1. Check whether Toolbox DOCKER environment variables are set:

   If this command returns no output, you are ready to use Docker Desktop.

   If it returns output (as shown in the example), unset the DOCKER environment variables to make the client talk to the Docker Desktop Engine (next step).

2. Run the unset command on the following DOCKER environment variables tounset them in the current shell.

Now, this command should return no output.

If you are using a Bash shell, you can use unset ${!DOCKER_*} to unset all DOCKER environment variables at once. (This does not work in other shells such as zsh; you need to unset each variable individually.)

Note: If you have a shell script as part of your profile that sets theseDOCKER environment variables automatically each time you open a commandwindow, then you need to unset these each time you want to use Docker Desktop.

If you install Docker Desktop on a machine where Docker Toolbox is installed.

Docker Desktop replaces the docker and docker-compose command lines in/usr/local/bin with symlinks to its own versions.

See also Unset environment variables in the currentshellin the Docker Machine topics.

Docker Toolbox and Docker Desktop coexistence

You can use Docker Desktop and Docker Toolbox together on the same machine. Whenyou want to use Docker Desktop make sure all DOCKER environment variables areunset. You can do this in bash with unset ${!DOCKER_*}. When you want to useone of the VirtualBox VMs you have set with docker-machine, just run a eval$(docker-machine env default) (or the name of the machine you want to target).This switches the current command shell to talk to the specified Toolboxmachine.

This setup is represented in the following diagram.

Using different versions of Docker tools

The coexistence setup works as is as long as your VirtualBox VMs provisionedwith docker-machine run the same version of Docker Engine as Docker Desktop.If you need to use VMs running older versions of Docker Engine, you can use atool like Docker Version Manager to manageseveral versions of docker client.

Checking component versions

Ideally, the Docker CLI client and Docker Engine should be the same version.Mismatches between client and server, and host machines you might havecreated with Docker Machine can cause problems (client can’t talk to the serveror host machines).

If you have already installed Docker Toolbox, and theninstalled Docker Desktop, you might get a newer version of the Docker client. Run docker version in a command shell to see client and server versions. In this example, the client installed with Docker Desktop is Version: 19.03.1 and the server (which was installed earlier with Toolbox) is Version: 19.03.2.

Also, if you created machines with Docker Machine (installed with Toolbox) thenupgraded or installed Docker Desktop, you might have machines running differentversions of Engine. Run docker-machine ls to view version information for themachines you created. In this example, the DOCKER column shows that each machineis running a different version of server.

You might also run into a similar situation with Docker Universal Control Plane (UCP).

There are a few ways to address this problem and keep using your oldermachines. One solution is to use a version manager likeDVM.

Migrating from Docker Toolbox to Docker Desktop on Mac

Docker Desktop does not propose Toolbox image migration as part of itsinstaller since version 18.01.0. You can migrate existing DockerToolbox images with the scripts described below. (This migrationcannot merge images from both Docker and Toolbox: any existing Docker image isreplaced by the Toolbox images.)

Run the following shell commands in a terminal. You need a workingqemu-img; it is part of the qemu package in both MacPorts and Brew:

First, find your Toolbox disk images. You probably have just one:~/.docker/machine/machines/default/disk.vmdk.

Second, find out the location and format of the disk image used by your DockerDesktop.

In this case the format is raw (it could have been qcow2), and the locationis ~/Library/Containers/com.docker.docker/Data/vms/0/.

Then:

• if your format is qcow2, run
• if your format is raw, run the following command. If you are short on diskspace, it is likely to fail.

Finally (optional), if you are done with Docker Toolbox, you may fullyuninstallit.

How do I uninstall Docker Toolbox?

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

This page contains information on how to diagnose and troubleshoot problems, send logs and communicate with the Docker Desktop team, use our forums and Knowledge Hub, browse and log issues on GitHub, and find workarounds for known problems.

Troubleshoot

Choose > Troubleshootfrom the menu bar to see the troubleshoot options.

The Troubleshoot page contains the following options:

• Restart Docker Desktop: Select to restart Docker Desktop.

• Run Diagnostics: Select this option to diagnose any issues on Docker Desktop. For detailed information about diagnostics, see Diagnose problems, send feedback, and create GitHub issues.

• Reset Kubernetes cluster: Select this option to delete all stacks and Kubernetes resources. For more information, see Kubernetes.

• Reset to factory defaults: Choose this option to reset all options onDocker Desktop to their initial state, the same as when Docker Desktop was first installed.

Diagnose problems, send feedback, and create GitHub issues

In-app diagnostics

If you experience issues for which you do not find solutions in thisdocumentation, on Docker Desktop for Windows issues onGitHub, or the Docker Desktop for Windowsforum, we can help youtroubleshoot the log data.

Choose > Troubleshootfrom the menu.

When the Diagnose & Feedback window initiated, it starts collecting diagnostics. When the diagnostics are available, you can upload them and obtain a Diagnostic ID, which must be provided when communicating with the Dockerteam. For more information on our policy regarding personal data, seehow is personal data handled in DockerDesktop.

If you click on Report an issue, it opens Docker Desktop for Windows issues onGitHub in your web browser in a“New issue” template, to be completed before submission. Do not forget toinclude your diagnostic ID.

Diagnosing from the terminal

On occasions it is useful to run the diagnostics yourself, for instance ifDocker Desktop for Windows cannot start.

First locate the com.docker.diagnose, that should be in C:ProgramFilesDockerDockerresourcescom.docker.diagnose.exe.

To create and upload diagnostics in Powershell, run:

After the diagnostics have finished, you should have the following output,containing your diagnostic ID:

Pick the client if you want to transfer files.

Troubleshooting topics

Make sure certificates are set up correctly

Docker Desktop ignores certificates listed under insecure registries, anddoes not send client certificates to them. Commands like docker run thatattempt to pull from the registry produces error messages on the command line,like this:

As well as on the registry. For example:

For more about using client and server side certificates, see How do I addcustom CA certificates? and Howdo I add client certificates? in theGetting Started topic.

Volumes

Permissions errors on data directories for shared volumes

Docker Desktop sets permissions on shared volumesto a default value of 0777(read, write, execute permissions for user and for group).

The default permissions on shared volumes are not configurable. If you areworking with applications that require permissions different from the sharedvolume defaults at container runtime, you need to either use non-host-mountedvolumes or find a way to make the applications work with the default filepermissions.

See also, Can I change permissions on shared volumes for container-specificdeploymentrequirements?in the FAQs.

inotify on shared drives does not work

Currently, inotify does not work on Docker Desktop. This becomes evident,for example, when an application needs to read/write to a container across amounted drive. Instead of relying on filesystem inotify, we recommend usingpolling features for your framework or programming language.

• Workaround for nodemon and Node.js - If you are usingnodemon with Node.js, try the fallbackpolling mode described here: nodemon isn’t restarting nodeapplications.

• Docker Desktop for Windows issue on GitHub - See the issue Inotify on shared drives does not work.

Volume mounting requires shared drives for Linux containers

If you are using mounted volumes and get runtime errors indicating anapplication file is not found, access is denied to a volume mount, or a servicecannot start, such as when using Docker Compose,you might need to enable shared drives.

Volume mounting requires shared drives for Linux containers (not for Windowscontainers). Click and then Settings > Shared Drives and share the drive that contains theDockerfile and volume.

Understand symlinks limitations

Symlinks work within and across containers. However, symlinks created outside ofcontainers (for example, on the host) do not work. To learn more, see Aresymlinks supported? in the FAQs.

Avoid unexpected syntax errors, use Unix style line endings for files in containers

Any file destined to run inside a container must use Unix style n lineendings. This includes files referenced at the command line for builds and inRUN commands in Docker files.

Docker containers and docker build run in a Unix environment, so files incontainers must use Unix style line endings: n, not Windows style: rn.Keep this in mind when authoring files such as shell scripts using Windowstools, where the default is likely to be Windows style line endings. Thesecommands ultimately get passed to Unix commands inside a Unix based container(for example, a shell script passed to /bin/sh). If Windows style line endingsare used, docker run fails with syntax errors.

For an example of this issue and the resolution, see this issue on GitHub:Docker RUN fails to execute shellscript.

Virtualization

For Docker Desktop to function correctly, your machine must have the following features:

1. Hyper-Vinstalled and working

2. Virtualization enabled

Hyper-V

Docker Desktop requires Hyper-V as well as the Hyper-V Module for WindowsPowershell to be installed and enabled. The Docker Desktop installer enablesit for you.

Docker Desktop also needs two CPU hardware features to use Hyper-V: Virtualization and Second Level Address Translation (SLAT), which is also called Rapid Virtualization Indexing (RVI). On some systems, Virtualization must be enabled in the BIOS. The steps required are vendor-specific, but typically the BIOS option is called Virtualization Technology (VTx) or something similar. Run the command systeminfo to check all required Hyper-V features. See Pre-requisites for Hyper-V on Windows 10 for more details.

To install Hyper-V manually, see Install Hyper-V on Windows 10. A reboot is required after installation. If you install Hyper-V without rebooting, Docker Desktop does not work correctly.

From the start menu, type Turn Windows features on or off and press enter.In the subsequent screen, verify that Hyper-V is enabled:

Hyper-V driver for Docker Machine

The Docker Desktop installation includes the legacy tool Docker Machine which uses the oldboot2docker.iso, and the Microsoft Hyper-Vdriver to create local virtual machines. This istangential to using Docker Desktop, but if you want to use Docker Machineto create multiple local Virtual Machines (VMs), or to provision remote machines, see the DockerMachine topics. This is documented only for users looking for information about Docker Machine on Windows, which requires that Hyper-V is enabled, an external network switch is active, and referenced in the flags for the docker-machine create command as described in the DockerMachine driver example.

Virtualization must be enabled

In addition to Hyper-V, virtualization must be enabled. Check thePerformance tab on the Task Manager:

If you manually uninstall Hyper-V or disable virtualization,Docker Desktop cannot start. See Unable to run Docker for Windows onWindows 10 Enterprise.

Networking and WiFi problems upon Docker Desktop for Windows install

Some users may experience networking issues during install and startup ofDocker Desktop. For example, upon install or auto-reboot, network adaptersand/or WiFi may get disabled. In some scenarios, problems are due to havingVirtualBox or its network adapters still installed, but in other scenarios thisis not the case. See the GitHub issue EnablingHyper-V feature turns my wi-fioff.

Here are some steps to take if you experience similar problems:

1. Ensure virtualization is enabled, as described above in Virtualizationmust be enabled.

2. Ensure Hyper-V is installed and enabled, as described above in Hyper-Vmust be enabled.

3. Ensure DockerNAT is enabled by checking the Virtual Switch Manageron the Actions tab on the right side of the Hyper-V Manager.

4. Set up an external network switch. If you plan at any point to use DockerMachine to set up multiple local VMs, you need thisanyway, as described in the topic on the Hyper-V driver for DockerMachine. You can replace DockerNATwith this switch.

5. If previous steps fail to solve the problems, follow steps on the CleanupREADME.

   Read the full description before you run the Windows cleanup script.

   The cleanup command has two flags, -Cleanup and-ForceDeleteAllSwitches. Read the whole page before running any scripts,especially warnings about -ForceDeleteAllSwitches. {: .warning}

Windows containers and Windows Server

Docker Desktop is not supported on Windows Server. Instead, you can useDocker Enterprise Basic at no additional cost.

If you have questions about how to run Windows containers on Windows 10, seeSwitch between Windows and Linuxcontainers.

A full tutorial is available in docker/labs atGetting Started with WindowsContainers.

You can install a native Windows binary which allows you to develop and runWindows containers without Docker Desktop. However, if you install Docker this way, you cannot develop or run Linux containers. If you try to run a Linux container on the native Docker daemon, an error occurs:

Limitations of Windows containers for localhost and published ports

Docker Desktop for Windows provides the option to switch Windows and Linux containers.If you are using Windows containers, keep in mind that there are somelimitations with regard to networking due to the current implementation ofWindows NAT (WinNAT). These limitations may potentially resolve as the Windowscontainers project evolves.

Windows containers work with published ports on localhost beginning with Windows 10 1809 using Docker Desktop for Windows as well as Windows Server 2019 / 1809 using Docker EE.

If you are working with a version prior to Windows 10 18.09, published ports on Windows containers have an issue with loopback to the localhost. You can only reach container endpoints from the host using the container’s IP and port. With Windows 10 18.09, containers work with published ports on localhost.

So, in a scenario where you use Docker to pull an image and run a webserver witha command like this:

Using curl http://localhost, or pointing your web browser athttp://localhost does not display the nginx web page (as it would do withLinux containers).

To reach a Windows container from the local host, you need to specify the IPaddress and port for the container that is running the service.

You can get the container IP address by using dockerinspect with some --format optionsand the ID or name of the container. For the example above, the command wouldlook like this, using the name we gave to the container (webserver) instead ofthe container ID:

This gives you the IP address of the container, for example:

Now you can connect to the webserver by using http://172.17.0.2:80 (or simplyhttp://172.17.0.2, since port 80 is the default HTTP port.)

For more information, see: Samsung j5 driver software.

• Docker Desktop for Windows issue on GitHub: Port binding does not work forlocahost

Running Docker Desktop in nested virtualization scenarios

Docker Desktop can run inside a Windows 10 VM running on apps like Parallels or VMware Fusion on a Mac provided that the VM is properly configured. However, problems and intermittent failures may still occur due to the way these apps virtualize the hardware. For these reasons, Docker Desktop is not supported in nested virtualization scenarios. It might workin some cases, and not in others.

For best results, we recommend you run Docker Desktop natively on a Windows system (to work with Windows or Linux containers), or on Mac to work with Linux containers.

If you still want to use nested virtualization

• Make sure nested virtualization support is enabled in VMWare or Parallels.Check the settings in Hardware > CPU & Memory > Advanced Options > Enablenested virtualization (the exact menu sequence might vary slightly).

• Configure your VM with at least 2 CPUs and sufficient memory to run yourworkloads.

• Make sure your system is more or less idle.

• Make sure your Windows OS is up-to-date. There have been several issues withsome insider builds.

• The processor you have may also be relevant. For example, Westmere based MacPros have some additional hardware virtualization features over Nehalem basedMac Pros and so do newer generations of Intel processors.

Typical failures we see with nested virtualization

• Slow boot time of the Linux VM. If you look in the logs and find some entriesprefixed with Moby. On real hardware, it takes 5-10 seconds to boot theLinux VM; roughly the time between the Connected log entry and the *Starting Docker .. [ ok ] log entry. If you boot the Linux VM inside aWindows VM, this may take considerably longer. We have a timeout of 60s or so.If the VM hasn’t started by that time, we retry. If the retry fails we printan error. You can sometimes work around this by providing more resources tothe Windows VM.

• Sometimes the VM fails to boot when Linux tries to calibrate the time stampcounter (TSC). This process is quite timing sensitive and may fail whenexecuted inside a VM which itself runs inside a VM. CPU utilization is alsolikely to be higher.

• Ensure “PMU Virtualization” is turned off in Parallels on Macs. Check thesettings in Hardware > CPU & Memory > Advanced Settings > PMUVirtualization.

Related issues

Discussion thread on GitHub at Docker for Windows issue267.

Networking issues

Some users have reported problems connecting to Docker Hub on the Docker Desktop stable version. (See GitHub issue22567.)

Here is an example command and error message:

As an immediate workaround to this problem, reset the DNS server to use theGoogle DNS fixed address: 8.8.8.8. You can configure this through the Settings

Network dialog, as described in the topic Network.Docker automatically restarts when you apply this setting, which could take sometime.

NAT/IP configuration

By default, Docker Desktop uses an internal network prefix of10.0.75.0/24. Should this clash with your normal network setup, you can changethe prefix from the Settings menu. See the Network topicunder Settings.

Workarounds

inotify currently does not work on Docker Desktop

If you are using Node.js with nodemon, a temporary workaround is to try thefallback polling mode described here: nodemon isn’t restarting nodeapplications. Seealso this issue on GitHub Inotify on shared drives does notwork.

Reboot

Restart your PC to stop / discard any vestige of the daemon running from thepreviously installed version.

Unset DOCKER_HOST

The DOCKER_HOST environmental variable does not need to be set. If you usebash, use the command unset ${!DOCKER_*} to unset it. For other shells,consult the shell’s documentation.

Make sure Docker is running for webserver examples

For the hello-world-nginx example and others, Docker Desktop must berunning to get to the webserver on http://localhost/. Make sure that theDocker whale is showing in the menu bar, and that you run the Docker commands ina shell that is connected to the Docker Desktop Engine (not Engine from Toolbox). Otherwise, you might start the webserver container but get a “web pagenot available” error when you go to docker.

How to solve port already allocated errors

If you see errors like Bind for 0.0.0.0:8080 failed: port is already allocatedor listen tcp:0.0.0.0:8080: bind: address is already in use ..

These errors are often caused by some other software on Windows using thoseports. To discover the identity of this software, either use the resmon.exeGUI and click “Network” and then “Listening Ports” or in a Powershell usenetstat -aon find /i 'listening ' to discover the PID of the processcurrently using the port (the PID is the number in the rightmost column). Decidewhether to shut the other process down, or to use a different port in yourdocker app.

Docker Desktop fails to start when anti-virus software is installed

Some anti-virus software may be incompatible with with Hyper-V and MicrosoftWindows 10 builds. The conflicttypically occurs after a Windows update andmanifests as an error response from the Docker daemon and a Docker Desktop start failure.

For a temporary workaround, uninstall the anti-virus software, orexplore other workarounds suggested on Docker Desktop forums.