Download Docker Desktop

Download Docker Desktop for Mac with Apple silicon
Download Docker Desktop for Mac with Intel chip
Download Docker Desktop for Windows

About Docker Desktop for Mac

  1. The Docker binaries are installed by default in /Applications/Docker.app/Contents/Resources/bin. Docker Desktop creates symlinks for the binaries in /usr/local/bin, which means they're automatically included in PATH on most systems.
  2. It is your responsibility to ensure that localhost is resolved to 127.0.0.1 and if Kubernetes is used, that kubernetes.docker.internal is resolved to 127.0.0.1.
  3. With Docker Desktop, the Docker daemon and containers run in a lightweight Linux VM managed by Docker. This means that although containers run by default as root, this doesn't grant root access to the Mac host machine.

About Docker Desktop for Windows

  1. Docker Desktop for Windows can be backended by either Windows Subsystem for Linux 2 (WSL 2) or Hyper-V. WSL 2 and Hyper-V have their own advantages and disadvantages, depending on your specific set up and your planned use case.
  2. WSL 2 backend: Turn on the WSL 2 feature on Windows. For detailed instructions, refer to the Microsoft documentation .
  3. Hyper-V backend: Turn on Hyper-V and Containers Windows features. For detailed instructions, refer to the Microsoft documentation .
  4. If your admin account is different to your user account, you must add the user to the docker-users group:
    1. Run Computer Management as an administrator.
    2. Navigate to Local Users and Groups > Groups > docker-users.
    3. Right-click to add the user to the group.
    4. Sign out and sign back in for the changes to take effect.

General Troubleshoot

I. Make sure certificates are set up correctly

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

Error response from daemon: Get http://192.168.203.139:5858/v2/: malformed HTTP response "\x15\x03\x01\x00\x02\x02"

As well as on the registry. For example:

2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52882: tls: client didn't provide a certificate

2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52883: tls: first record does not look like a TLS handshake

II. Docker Desktop's UI appears green, distorted, or has visual artifacts

Docker Desktop uses hardware-accelerated graphics by default, which may cause problems for some GPUs. In such cases, Docker Desktop will launch successfully, but some screens may appear green, distorted, or have some visual artifacts.

To work around this issue, disable hardware acceleration by creating a "disableHardwareAcceleration": true entry in Docker Desktop's settings.json file. You can find this file at:

Mac: ~/Library/Group Containers/group.com.docker/settings.json
Windows: C:\Users\[USERNAME]\AppData\Roaming\Docker\settings.json

After updating the settings.json file, close and restart Docker Desktop to apply the changes.

Troubleshoot for Mac

I. Docker Desktop fails to start on MacOS

On MacOS, Docker Desktop creates Unix domain sockets used for inter-process communication. Docker fails to start if the absolute path length of any of these sockets exceeds the OS limitation which is 104 characters on MacOS. If the user ID length is such that the absolute path of the socket exceeds the OS path length limitation, then Docker Desktop is unable to create the socket and fails to start. The workaround for this is to shorten the user ID which we recommend has a maximum length of 33 characters on MacOS.

Following are the examples of errors on MacOS which indicate that the startup failure was due to exceeding the above mentioned OS limitation:

[vpnkit-bridge][F] listen unix <HOME>/Library/Containers/com.docker.docker/Data/http-proxy-control.sock: bind: invalid argument

[com.docker.backend][E] listen(vsock:4099) failed: listen unix <HOME>/Library/Containers/com.docker.docker/Data/vms/0/00000002.00001003: bind: invalid argument

II. Incompatible CPU detected

Docker Desktop requires a processor (CPU) that supports virtualization and, more specifically, the Apple Hypervisor framework. Docker Desktop is only compatible with Mac systems that have a CPU that supports the Hypervisor framework. Most Macs built in 2010 and later support it,as described in the Apple Hypervisor Framework documentation about supported hardware:

Generally, machines with an Intel VT-x feature set that includes Extended Page Tables (EPT) and Unrestricted Mode are supported.

To check if your Mac supports the Hypervisor framework, run the following command in a terminal window.

sysctl kern.hv_support

If your Mac supports the Hypervisor Framework, the command prints kern.hv_support: 1.
If not, the command prints kern.hv_support: 0.

III. VPNKit keeps breaking

In Docker Desktop version 4.19, gVisor replaced VPNKit to enhance the performance of VM networking when using the Virtualization framework on macOS Ventura and above.

To continue using VPNKit, add "networkType":"vpnkit" to your settings.json file located at ~/Library/Group Containers/group.com.docker/settings.json.

Troubleshoot for Windows

I. Permissions errors on data directories for shared volumes

When sharing files from Windows, Docker Desktop sets permissions on shared volumes to 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 are working with applications that require permissions different from the shared volume defaults at container runtime, you need to either use non-host-mounted volumes or find a way to make the applications work with the default file permissions.

II. Volume mounting requires shared folders for Linux containers

If you are using mounted volumes and get runtime errors indicating an application file is not found, access is denied to a volume mount, or a service cannot start, such as when using Docker Compose, you might need to turn on shared folders.

With the Hyper-V backend, mounting files from Windows requires shared folders for Linux containers. From Settings, select Shared Folders and share the folder that contains the Dockerfile and volume.

III. 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 line endings. This includes files referenced at the command line for builds and in RUN commands in Docker files.

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

IV. Virtualization for WSL 2 and Windows Home

Enable the following features:
  1. Virtual Machine Platform
  2. Windows Subsystem for Linux
  3. Virtualization enabled in the BIOS
  4. Hypervisor enabled at Windows startup

V. Virtualization for Hyper-V

On Windows 10 Pro or Enterprise, you can also use Hyper-V with the following features enabled:
  1. Hyper-V installed and working
  2. Virtualization enabled in the BIOS
  3. Hypervisor enabled at Windows startup
Docker Desktop requires Hyper-V as well as the Hyper-V Module for Windows PowerShell to be installed and enabled. The Docker Desktop installer enables it 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.

VI. Turn on Virtualization

In addition to Hyper-V or WSL 2, virtualization must be turned on. Check the Performance tab on the Task Manager. Alternatively, you can type 'systeminfo' into your terminal. If you see 'Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed', then virtualization is enabled.

If you manually uninstall Hyper-V, WSL 2 or turn off virtualization, Docker Desktop cannot start.

VII. Hypervisor enabled at Windows startup

If you have completed the steps described above and are still experiencing Docker Desktop startup issues, this could be because the Hypervisor is installed, but not launched during Windows startup. Some tools (such as older versions of Virtual Box) and video game installers turn off hypervisor on boot. To turn it back on:
  1. Open an administrative console prompt.
  2. Run bcdedit /set hypervisorlaunchtype auto.
  3. Restart Windows.

VIII. Docker Desktop Access Denied error message when starting Docker Desktop

Docker Desktop displays the Docker Desktop - Access Denied error if a Windows user is not part of the docker-users group.

If your admin account is different to your user account, add the docker-users group. Run Computer Management as an administrator and navigate to Local Users and Groups > Groups > docker-users.

Right-click to add the user to the group. Sign out and sign back in for the changes to take effect.
@2023 SeedTech 京ICP备2022018038号-1 京公网安备11010802041477号 Contact Us: support@seedtech.club