From aecc6302a45d04fa7a8734797497af31504a5575 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 1 Apr 2026 10:49:29 +0100 Subject: [PATCH 1/4] ENGDOCS-3223 --- content/manuals/admin/organization/onboard.md | 2 +- .../desktop/setup/install/windows-install.md | 67 ++++++++++++++----- .../windows-permission-requirements.md | 45 +++++++++++-- 3 files changed, 89 insertions(+), 25 deletions(-) diff --git a/content/manuals/admin/organization/onboard.md b/content/manuals/admin/organization/onboard.md index 2c206bf5b6ca..035c7c8bc574 100644 --- a/content/manuals/admin/organization/onboard.md +++ b/content/manuals/admin/organization/onboard.md @@ -76,7 +76,7 @@ receive your Docker subscription benefits. identify Docker users by checking if Docker Desktop is installed at the following location on each user's machine: - Mac: `/Applications/Docker.app` - - Windows: `C:\Program Files\Docker\Docker` + - Windows: `C:\Program Files\Docker\Docker`(all-user installation) or `%LOCALAPPDATA%\Programs\DockerDesktop` (per-user installation) - Linux: `/opt/docker-desktop` - If your organization doesn't use device management software or your users haven't installed Docker Desktop yet, you can survey your users to diff --git a/content/manuals/desktop/setup/install/windows-install.md b/content/manuals/desktop/setup/install/windows-install.md index 520e43a22058..9b0b392a1ab9 100644 --- a/content/manuals/desktop/setup/install/windows-install.md +++ b/content/manuals/desktop/setup/install/windows-install.md @@ -36,13 +36,27 @@ This page provides download links, system requirements, and step-by-step install _For checksums, see [Release notes](/manuals/desktop/release-notes.md)_ +## Installation modes + +Docker Desktop supports two installation modes. Per-user installation is recommended for most users. It does not require administrator privileges to install or update, and the WSL 2 backend it uses covers the needs of the vast majority of Docker Desktop users. + +| | Per-user (recommended) | All users | +|---|---|---| +| Install location | `%LOCALAPPDATA%\Programs\DockerDesktop` | `C:\Program Files\Docker\Docker` | +| 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 | +| Windows containers | Not supported | Supported | + + ## System requirements > [!TIP] > > **Should I use Hyper-V or WSL?** > -> 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. +> 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. {{< tabs >}} {{< tab name="WSL 2 backend, x86_64" >}} @@ -131,7 +145,11 @@ For more information, see [Running Docker Desktop in a VM or VDI environment](/m 1. Download the installer using the download button at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md). -2. Double-click `Docker Desktop Installer.exe` to run the installer. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`. +2. Double-click `Docker Desktop Installer.exe` to run the installer. Docker Desktop installs in per-user mode by default, to `%LOCALAPPDATA%\Programs\DockerDesktop`. + + > [!NOTE] + > + > To install for all users instead, run the installer from an administrator command prompt. See [Install from the command line](#install-from-the-command-line). 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. @@ -143,36 +161,43 @@ For more information, see [Running Docker Desktop in a VM or VDI environment](/m 6. [Start Docker Desktop](#start-docker-desktop). -If your administrator account is different to your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers: +### Install from the command line -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. +After downloading `Docker Desktop Installer.exe`, run the following command in a terminal to install Docker Desktop to `%LOCALAPPDATA%\Programs\DockerDesktop`. -### Install from the command line +By default, the installer runs in per-user mode and does not require administrator privileges: -After downloading `Docker Desktop Installer.exe`, run the following command in a terminal to install Docker Desktop: +```console +$ "Docker Desktop Installer.exe" install --user +``` +To install for all users on the machine (requires administrator privileges): + ```console $ "Docker Desktop Installer.exe" install ``` -If you’re using PowerShell you should run it as: - +If you're using PowerShell you should run it as: + ```powershell +# Per-user installation (no admin required) +Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--user' + +# All-users installation (run as administrator) Start-Process 'Docker Desktop Installer.exe' -Wait install ``` If using the Windows Command Prompt: - + ```sh +# Per-user installation (no admin required) +start /w "" "Docker Desktop Installer.exe" install --user + +# All-users installation (run as administrator) start /w "" "Docker Desktop Installer.exe" install ``` -By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`. - -If your administrator account is different to your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers. +If using all-users installation and your administrator account is different to your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers: ```console $ net localgroup docker-users /add @@ -249,6 +274,8 @@ If Microsoft Store access is blocked due to security policies: #### Installation behavior + +- `--user`: Installs Docker Desktop in per-user mode, to `%LOCALAPPDATA%\Programs\DockerDesktop`. No administrator privileges are required. This is the recommended mode for most users. See [Installation modes](#installation-modes). - `--quiet`: Suppresses information output when running the installer - `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run - `--installation-dir=`: Changes the default installation location (`C:\Program Files\Docker\Docker`) @@ -293,13 +320,19 @@ If Microsoft Store access is blocked due to security policies: ### Administrator privileges -Installing Docker Desktop requires administrator privileges. However, once installed, it can be used without administrative access. Some actions, though, still need elevated permissions. See [Understand permission requirements for Windows](./windows-permission-requirements.md) for more detail. +In per-user mode, Docker Desktop can be installed and updated without administrator privileges. Some settings still require elevation and are marked **Requires password** in the Settings UI. Enabling WSL 2 for the first time also requires administrator privileges, but this is a one-time, per-machine operation. + +In all-users mode, installing Docker Desktop requires administrator privileges. However, once installed, it can be used without administrative access. Some actions, though, still need elevated permissions. See [Understand permission requirements for Windows](./windows-permission-requirements.md) for more detail. See the [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md#how-do-i-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. If you're an IT admin and your users do not have administrator rights and plan to perform operations that require elevated privileges, be sure to install Docker Desktop using the `--always-run-service` installer flag. This ensures those actions can still be executed without prompting for User Account Control (UAC) elevation. See [Installer Flags](#installer-flags) for more detail. -### Windows containers +### Windows containers + +> [!NOTE] +> +> Windows containers are only supported in all-users installation mode. They are not available when Docker Desktop is installed per-user. From the Docker Desktop menu, you can toggle which daemon (Linux or Windows) the Docker CLI talks to. Select **Switch to Windows containers** to use Windows diff --git a/content/manuals/desktop/setup/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md index d9ad5f9a249e..74fcd55718c4 100644 --- a/content/manuals/desktop/setup/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -18,22 +18,49 @@ Docker Desktop on Windows is designed with security in mind. Administrative righ ## Permission requirements -While Docker Desktop on Windows can be run without having `Administrator` privileges, it does require them during installation. On installation you receive a UAC prompt which allows a privileged helper service to be installed. After that, Docker Desktop can be run without administrator privileges. - -Running Docker Desktop on Windows without the privileged helper does not require users to have `docker-users` group membership. However, -some features that require privileged operations will have this requirement. - -If you performed the installation, you are automatically added to this group, but other users must be added manually. This allows the administrator to control who has access to features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers. - +The permissions required to install and run Docker Desktop depend on which [installation mode](/manuals/desktop/setup/install/windows-install.md#installation-modes) you use. + +### Per-user installation + +In per-user mode, Docker Desktop installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and writes only to current-user registry keys (`HKCU`). This means: + +- No administrator privileges are required to install or update Docker Desktop. +- After installation, Docker Desktop can be run without administrator privileges. +- Some settings marked **Requires password** in the Settings UI still require elevation. When you change one of these settings and select **Apply**, Docker Desktop prompts for administrator credentials. + +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. + +### All-users installation + +In all-users mode, Docker Desktop installs to `C:\Program Files\Docker\Docker` and writes to Local Machine registry keys (`HKLM`). Both locations require administrator privileges to modify, so: + +- Administrator privileges are required to install and update Docker Desktop. +- On installation you receive a UAC prompt which allows the privileged helper service `com.docker.service` to be installed. +- After installation, Docker Desktop can be run without administrator privileges. + +Running Docker Desktop without the privileged helper does not require users to have `docker-users` group membership. However, some features that require privileged operations will have this requirement. + +If you performed the installation, you are automatically added to the `docker-users` group, but other users must be added manually. This allows the administrator to control who has access to features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers. + When Docker Desktop launches, all non-privileged named pipes are created so that only the following users can access them: - The user that launched Docker Desktop. - Members of the local `Administrators` group. - The `LOCALSYSTEM` account. + +### Operations that always require elevation + +The following require administrator privileges regardless of installation mode. + +- Enabling WSL 2 for the first time: WSL 2 must be enabled on the machine before Docker Desktop can run. This is a one-time, per-machine operation. Once WSL 2 is enabled, it does not need to be enabled again for subsequent Docker Desktop installs or updates. +- Settings marked **Requires password**: Certain Docker Desktop settings affect system-level configuration and require administrator credentials to apply. These are clearly marked **Requires password** in the Settings UI. When you change one of these settings and click **Apply**, Docker Desktop prompts for administrator credentials. ## Privileged helper Docker Desktop needs to perform a limited set of privileged operations which are conducted by the privileged helper process `com.docker.service`. This approach allows, following the principle of least privilege, `Administrator` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user. +> [!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. 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. @@ -84,6 +111,10 @@ isolated from the Docker daemon and other services running inside the VM. > > Enabling Windows containers has important security implications. +> [!NOTE] +> +> Windows containers are only supported in all-users installation mode. They are not available when Docker Desktop is installed per-user. See [Installation modes](/manuals/desktop/setup/install/windows-install.md#installation-modes). + Unlike the Linux Docker Engine and containers which run in a VM, Windows containers are implemented using operating system features, and run directly on the Windows host. If you enable Windows containers during installation, the `ContainerAdministrator` user used for administration inside the container is a local administrator on the host machine. Enabling Windows containers during installation makes it so that members of the `docker-users` group are able to elevate to administrators on the host. For organizations who don't want their developers to run Windows containers, a `-–no-windows-containers` installer flag is available to disable their use. ## Networking From 2b1737f9b5f39208905363a0a8bfa1699a01e933 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 1 Apr 2026 10:54:41 +0100 Subject: [PATCH 2/4] edit --- content/manuals/desktop/setup/install/windows-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/desktop/setup/install/windows-install.md b/content/manuals/desktop/setup/install/windows-install.md index 9b0b392a1ab9..ea95d824f45b 100644 --- a/content/manuals/desktop/setup/install/windows-install.md +++ b/content/manuals/desktop/setup/install/windows-install.md @@ -43,7 +43,7 @@ Docker Desktop supports two installation modes. Per-user installation is recomme | | Per-user (recommended) | All users | |---|---|---| | Install location | `%LOCALAPPDATA%\Programs\DockerDesktop` | `C:\Program Files\Docker\Docker` | -| Registry keys** | Current User (HKCU) | Local Machine (HKLM) | +| 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 | From fa4968db5bd39d7cf6cd4ebee778c6970435d43d Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 2 Apr 2026 11:47:54 +0100 Subject: [PATCH 3/4] SME review fixes --- .../manuals/desktop/setup/install/windows-install.md | 10 ++++++++-- .../setup/install/windows-permission-requirements.md | 6 +++--- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/content/manuals/desktop/setup/install/windows-install.md b/content/manuals/desktop/setup/install/windows-install.md index ea95d824f45b..948a6609be4b 100644 --- a/content/manuals/desktop/setup/install/windows-install.md +++ b/content/manuals/desktop/setup/install/windows-install.md @@ -48,7 +48,9 @@ Docker Desktop supports two installation modes. Per-user installation is recomme | Admin rights to update | Not required | Required | | Linux containers backend | WSL 2 only | WSL 2 or Hyper-V | | Windows containers | Not supported | Supported | +| Security | Smaller attack surface; no privileged system service installed | Requires privileged system service; broader access to host resources | +For more information, see [Understand permission requirements for Windows](windows-install.md). ## System requirements @@ -145,11 +147,11 @@ For more information, see [Running Docker Desktop in a VM or VDI environment](/m 1. Download the installer using the download button at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md). -2. Double-click `Docker Desktop Installer.exe` to run the installer. Docker Desktop installs in per-user mode by default, to `%LOCALAPPDATA%\Programs\DockerDesktop`. +2. Double-click `Docker Desktop Installer.exe` to run the installer. The installer will ask which installation mode you prefer. Choosing per-user installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and requires no administrator privileges. This is the default. Choosing all users will prompt for elevation. > [!NOTE] > - > To install for all users instead, run the installer from an administrator command prompt. See [Install from the command line](#install-from-the-command-line). + >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. @@ -205,6 +207,10 @@ $ net localgroup docker-users /add See the [Installer flags](#installer-flags) section to see what flags the `install` command accepts. +> [!NOTE] +> +>If you want to switch installation mode at a later date, you need to uninstall and reinstall Docker Desktop. + ## Start Docker Desktop Docker Desktop does not start automatically after installation. To start Docker Desktop: diff --git a/content/manuals/desktop/setup/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md index 74fcd55718c4..f710a1938360 100644 --- a/content/manuals/desktop/setup/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -12,7 +12,7 @@ weight: 40 This page contains information about the permission requirements for running and installing Docker Desktop on Windows, the functionality of the privileged helper process `com.docker.service`, and the reasoning behind this approach. -It also provides clarity on running containers as `root` as opposed to having `Administrator` access on the host and the privileges of the Windows Docker engine and Windows containers. +It also provides clarity on running containers as `root` as opposed to having `Administrator` access on the host and the privileges of Docker Engine and Windows containers. Docker Desktop on Windows is designed with security in mind. Administrative rights are only required when absolutely necessary. @@ -26,7 +26,7 @@ In per-user mode, Docker Desktop installs to `%LOCALAPPDATA%\Programs\DockerDesk - No administrator privileges are required to install or update Docker Desktop. - After installation, Docker Desktop can be run without administrator privileges. -- Some settings marked **Requires password** in the Settings UI still require elevation. When you change one of these settings and select **Apply**, Docker Desktop prompts for administrator credentials. +- 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. @@ -52,7 +52,7 @@ When Docker Desktop launches, all non-privileged named pipes are created so that The following require administrator privileges regardless of installation mode. - Enabling WSL 2 for the first time: WSL 2 must be enabled on the machine before Docker Desktop can run. This is a one-time, per-machine operation. Once WSL 2 is enabled, it does not need to be enabled again for subsequent Docker Desktop installs or updates. -- Settings marked **Requires password**: Certain Docker Desktop settings affect system-level configuration and require administrator credentials to apply. These are clearly marked **Requires password** in the Settings UI. When you change one of these settings and click **Apply**, Docker Desktop prompts for administrator credentials. +- Settings marked **Requires password**: Certain Docker Desktop settings affect system-level configuration and require administrator credentials to apply. These are clearly marked **Requires password**. When you change one of these settings and click **Apply**, Docker Desktop prompts for administrator credentials. ## Privileged helper From eede86a536ed9bb0c3a5f0ede97bb56fa22ed863 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 2 Apr 2026 11:48:55 +0100 Subject: [PATCH 4/4] vale --- .../desktop/setup/install/windows-permission-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/desktop/setup/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md index f710a1938360..222e42e0c420 100644 --- a/content/manuals/desktop/setup/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -52,7 +52,7 @@ When Docker Desktop launches, all non-privileged named pipes are created so that The following require administrator privileges regardless of installation mode. - Enabling WSL 2 for the first time: WSL 2 must be enabled on the machine before Docker Desktop can run. This is a one-time, per-machine operation. Once WSL 2 is enabled, it does not need to be enabled again for subsequent Docker Desktop installs or updates. -- Settings marked **Requires password**: Certain Docker Desktop settings affect system-level configuration and require administrator credentials to apply. These are clearly marked **Requires password**. When you change one of these settings and click **Apply**, Docker Desktop prompts for administrator credentials. +- Settings marked **Requires password**: Certain Docker Desktop settings affect system-level configuration and require administrator credentials to apply. These are clearly marked **Requires password**. When you change one of these settings and select **Apply**, Docker Desktop prompts for administrator credentials. ## Privileged helper