diff --git a/content/manuals/desktop/features/vmm.md b/content/manuals/desktop/features/vmm.md index f3b3f04d349e..d8fc0622a8ec 100644 --- a/content/manuals/desktop/features/vmm.md +++ b/content/manuals/desktop/features/vmm.md @@ -1,59 +1,90 @@ --- -title: Virtual Machine Manager for Docker Desktop on Mac +title: Virtual Machine Manager linkTitle: Virtual Machine Manager -keywords: virtualization software, resource allocation, mac, docker desktop, vm monitoring, vm performance, apple silicon -description: Discover Docker Desktop for Mac's Virtual Machine Manager (VMM) options, including Docker VMM for Apple Silicon, offering enhanced performance and efficiency +keywords: virtualization software, resource allocation, mac, windows, docker desktop, vm performance, apple silicon, wsl, hyper-v +description: Learn about Docker Desktop's Virtual Machine Manager options, including Docker VMM for Mac and Windows weight: 110 +params: + sidebar: + badge: + color: blue + text: Updated --- -Docker Desktop supports multiple Virtual Machine Managers (VMMs) to power the Linux VM that runs containers. You can choose the most suitable option based on your system architecture (Intel or Apple Silicon), performance needs, and feature requirements. This page provides an overview of the available options. - -To change the VMM, go to **Settings** > **General** > **Virtual Machine Manager**. +Docker Desktop supports multiple Virtual Machine Managers (VMMs) to power the Linux VM that runs containers. The options available depend on your platform. ## Docker VMM {{< summary-bar feature_name="VMM" >}} -Docker VMM is a container-optimized hypervisor. By optimizing both the Linux kernel and hypervisor layers, Docker VMM delivers significant performance enhancements across common developer tasks. +Docker VMM is a container-optimized hypervisor. From Docker Desktop 4.86, Docker VMM uses Docker's own hypervisor, replacing `libkrun` used in version 4.35 - 4.85 for Mac users. Built specifically for container workloads, Docker VMM: -Some key performance enhancements provided by Docker VMM include: +- Returns idle memory to the host when containers aren't active, so Docker Desktop doesn't hold RAM it's not using +- Improves file I/O between container and host, reducing latency in the edit-compile-test loop +- Reduces engine and container start-up time -- Faster I/O operations: With a cold cache, iterating over a large shared filesystem with `find` is 2x faster than when the Apple Virtualization framework is used. -- Improved caching: With a warm cache, performance can improve by as much as 25x, even surpassing native Mac operations. +Because Docker controls the virtualization layer, it can be monitored and governed in ways that aren't possible with third-party backends. On Windows, Docker VMM provides a stable alternative to WSL 2 with a real VM boundary between the container environment and the host. -These improvements directly impact developers who rely on frequent file access and overall system responsiveness during containerized development. Docker VMM marks a significant leap in speed, enabling smoother workflows and faster iteration cycles. +### Switch to Docker VMM -> [!NOTE] -> -> Docker VMM requires a minimum of 4GB of memory to be allocated to the Docker Linux VM. The memory needs to be increased before Docker VMM is enabled, and this can be done from the **Resources** tab in **Settings**. +Docker VMM requires a minimum of 4 GB of memory allocated to the Docker Linux VM. Increase memory in **Settings** > **Resources** before switching. -### Known issues +{{< tabs >}} +{{< tab name="Mac (Apple Silicon)" >}} -As Docker VMM is still in Beta, there are a few known limitations: +1. Go to **Settings** > **General** > **Virtual Machine Manager**. +2. Select **Docker VMM**. +3. Select **Apply & restart**. -- Docker VMM does not currently support Rosetta, so emulation of amd64 architectures is slow. Docker is exploring potential solutions. -- Certain databases, like MongoDB and Cassandra, may fail when using virtiofs with Docker VMM. This issue is expected to be resolved in a future release. +If you previously had Docker VMM selected, which engine runs depends on your version: -## Apple Virtualization framework +- Docker Desktop 4.35 and earlier is backed by `libkrun` +- Docker Desktop 4.86 and later is backed by Docker's own hypervisor -The Apple Virtualization framework is a stable and well-established option for managing virtual machines on Mac. It has been a reliable choice for many Mac users over the years. This framework is best suited for developers who prefer a proven solution with solid performance and broad compatibility. +If you're upgrading from version 4.35 onwards, your setting is preserved and Docker Desktop switches to the new Docker VMM automatically on restart. -## QEMU (Legacy) for Apple Silicon +{{< /tab >}} +{{< tab name="Windows" >}} -> [!NOTE] -> -> QEMU has been deprecated in versions 4.44 and later. For more information, see the [blog announcement](https://www.docker.com/blog/docker-desktop-for-mac-qemu-virtualization-option-to-be-deprecated-in-90-days/) +1. Go to **Settings** > **General** > **Virtual Machine Manager**. +2. Select **Docker VMM**. +3. Select **Apply & restart**. + +{{< /tab >}} +{{< /tabs >}} + +### Known issues -QEMU is a legacy virtualization option for Apple Silicon Macs, primarily supported for older use cases. +- A restart of Docker Desktop may be required after switching to Docker VMM. +- Docker VMM does not support bind mount auto-shares. If you see a `file is not shared from the host` error, go to **Settings** > **Resources** > **File sharing** and add the directory you want to share. -Docker recommends transitioning to newer alternatives, such as Docker VMM or the Apple Virtualization framework, as they offer superior performance and ongoing support. Docker VMM, in particular, offers substantial speed improvements and a more efficient development environment, making it a compelling choice for developers working with Apple Silicon. +#### Mac only -Note that this is not related to using QEMU to emulate non-native architectures in [multi-platform builds](/manuals/build/building/multi-platform.md#qemu). +- Docker VMM does not currently support Rosetta, so emulation of amd64 architectures is slow. Docker is exploring potential solutions. +- Certain databases, such as MongoDB and Cassandra, may fail when using virtiofs with Docker VMM. This issue is expected to be resolved in a future release. + +## Alternative VMMs for Mac + +### Apple Virtualization framework -## HyperKit (Legacy) for Intel-based Macs +The Apple Virtualization framework is a stable and well-established option for managing virtual machines on Mac. It has been a reliable choice for many Mac users over the years. + +### HyperKit (Legacy) for Intel-based Macs > [!NOTE] > > HyperKit is deprecated. Docker recommends switching to the Apple Virtualization framework. HyperKit is a legacy virtualization option for Intel-based Macs. Docker recommends switching to modern alternatives for better performance and to future-proof your setup. + +## Alternative VMMs for Windows + +### WSL 2 + +WSL 2 (Windows Subsystem for Linux 2) is the default Windows backend for Docker Desktop. It runs a full Linux kernel inside a lightweight VM with tight integration into the Windows host file system and networking. WSL 2 is available in both per-user and all-users installation modes and does not require administrator privileges. + +For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). + +### Hyper-V + +Hyper-V is Windows' native hypervisor. It runs the Docker Linux VM in a fully isolated virtual machine, providing a strong boundary between the container environment and the Windows host. Hyper-V is only available in all-users installation mode and requires administrator privileges. diff --git a/content/manuals/desktop/settings-and-maintenance/settings.md b/content/manuals/desktop/settings-and-maintenance/settings.md index 931d71513a97..51d889f266e6 100644 --- a/content/manuals/desktop/settings-and-maintenance/settings.md +++ b/content/manuals/desktop/settings-and-maintenance/settings.md @@ -44,7 +44,7 @@ Configure startup behavior, UI appearance, terminal preferences, and feature def | **Expose daemon on tcp://localhost:2375 without TLS** | Allow legacy clients to connect to the Docker daemon. Use with caution as exposing the daemon without TLS can result in remote code execution attacks. | Disabled | Windows (Hyper-V backend only) | | | **Use the WSL 2 based engine** | WSL 2 provides better performance than the Hyper-V backend. For more information, see [Docker Desktop WSL 2 backend](/manuals/desktop/features/wsl/_index.md). | Disabled | Windows | | | **Add \*.docker.internal to host file** | Adds internal DNS entries. | Enabled | Windows | Helps resolve Docker-internal domains | -| **Choose Virtual Machine Manager (VMM)** | Choose the VMM for creating and managing the Docker Desktop Linux VM. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). | | Mac | Select **Docker VMM** for the latest and most performant Hypervisor/Virtual Machine Manager. This option is available only on Apple Silicon Macs and is in Beta.| +| **Choose Virtual Machine Manager (VMM)** | Choose the VMM for creating and managing the Docker Desktop Linux VM. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). | | Mac, Windows | Select **Docker VMM** for optimized container performance. Docker VMM is in Beta. | | **Choose file sharing implementation for your containers** | Choose whether you want to share files using **VirtioFS**, or **gRPC FUSE** | **VirtioFS** | Mac | Use VirtioFS for speedy file sharing. VirtioFS has reduced the time taken to complete filesystem operations by [up to 98%](https://github.com/docker/roadmap/issues/7#issuecomment-1044452206). It is the only file sharing implementation supported by Docker VMM. | |**Use Rosetta for x86_64/amd64 emulation on Apple Silicon** | Accelerate x86/AMD64 binary emulation on Apple Silicon. This option is only available if you have selected **Apple Virtualization framework** as the Virtual Machine Manager. | Disabled | Mac | | | **Send usage statistics** | Send diagnostics, crash reports, and usage data to Docker to improve and troubleshoot the application. Docker may periodically prompt you for more information. | Enabled | All | | diff --git a/content/manuals/desktop/setup/install/windows-install.md b/content/manuals/desktop/setup/install/windows-install.md index ca473a689de4..ea12b9c2c85c 100644 --- a/content/manuals/desktop/setup/install/windows-install.md +++ b/content/manuals/desktop/setup/install/windows-install.md @@ -40,7 +40,7 @@ Docker Desktop supports two installation modes. Per-user installation is recomme | Registry keys | Current User (HKCU) | Local Machine (HKLM) | | Admin rights to install | Not required | Required | | Admin rights to update | Not required | Required | -| Linux containers backend | WSL 2 only | WSL 2 or Hyper-V | +| Linux containers backend | WSL 2 or Docker VMM | WSL 2, Hyper-V, or Docker VMM | | Windows containers | Not supported | Supported | | Security | Smaller attack surface; no privileged system service installed | Requires privileged system service; broader access to host resources | @@ -50,9 +50,9 @@ For more information, see [Understand permission requirements for Windows](windo > [!TIP] > -> **Should I use Hyper-V or WSL?** +> **Which backend should I use?** > -> Docker Desktop's functionality remains consistent on both WSL and Hyper-V, without a preference for either architecture. Hyper-V and WSL have their own advantages and disadvantages, depending on your specific setup and your planned use case. Note that Hyper-V is only available with all-users installation. If you install Docker Desktop in per-user mode, WSL 2 is the only supported backend. +> Docker Desktop for Windows supports three backends: WSL 2, Hyper-V, and Docker VMM (Beta). WSL 2 is the default and works for most users without administrator privileges. Hyper-V is only available with all-users installation. Docker VMM is a container-optimized hypervisor that reclaims idle memory and improves file I/O. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md). {{< tabs >}} {{< tab name="WSL 2 backend, x86_64" >}} @@ -150,7 +150,7 @@ For more information, see [Running Docker Desktop in a VM or VDI environment](/m > >If you want to switch installation mode at a later date, you need to uninstall and reinstall Docker Desktop. -3. When prompted, ensure the **Use WSL 2 instead of Hyper-V** option on the Configuration page is selected or not depending on your choice of backend. +3. When prompted, select your backend on the Configuration page: **Use WSL 2 instead of Hyper-V** for WSL 2, or leave it unselected for Hyper-V. You can switch to Docker VMM after installation from **Settings** > **General**. On systems that support only one backend, Docker Desktop automatically selects the available option. diff --git a/content/manuals/desktop/setup/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md index 165e2b3c36e8..88c27e2911da 100644 --- a/content/manuals/desktop/setup/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -24,7 +24,7 @@ In per-user mode, Docker Desktop installs to `%LOCALAPPDATA%\Programs\DockerDesk - After installation, Docker Desktop can be run without administrator privileges. - Some settings marked **Requires password** in **Settings** still require elevation. When you change one of these settings and select **Apply**, Docker Desktop opens a UAC prompt for administrator access. -Per-user installation does not install the privileged helper service `com.docker.service` automatically. As a result, features that depend on it, such as the Hyper-V backend and Windows containers, are not available. For most users this is not a limitation, as the WSL 2 backend covers the majority of use cases. +Per-user installation does not install the privileged helper service `com.docker.service` automatically. As a result, features that depend on it, such as the Hyper-V backend and Windows containers, are not available. Docker VMM (Beta) is available in per-user mode and does not require the privileged helper. For most users, the WSL 2 or Docker VMM backend covers the majority of use cases. ### All-users installation @@ -56,7 +56,7 @@ Docker Desktop needs to perform a limited set of privileged operations which are > [!NOTE] > -> `com.docker.service` is only installed in all-users installation mode. It is not used in per-user installation, which instead relies solely on the WSL 2 backend and does not support Hyper-V or Windows containers. +> `com.docker.service` is only installed in all-users installation mode. It is not used in per-user installation, which relies on the WSL 2 or Docker VMM backend and does not support Hyper-V or Windows containers. The privileged helper `com.docker.service` is a Windows service which runs in the background with `SYSTEM` privileges. It listens on the named pipe `//./pipe/dockerBackendV2`. The developer runs the Docker Desktop application, which connects to the named pipe and sends commands to the service. This named pipe is protected, and only users that are part of the `docker-users` group can have access to it. diff --git a/data/summary.yaml b/data/summary.yaml index 3521d8779605..1a5872e976d6 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -281,7 +281,8 @@ Synchronized file sharing: USB/IP support: for: Docker Desktop for Mac, Linux, and Windows with the Hyper-V backend VMM: - for: Docker Desktop on Mac with Apple Silicon + availability: Beta + requires: "Docker Desktop 4.86 or later" Wasm workloads: availability: Beta Wasmtime: