Skip to content

Engdocs 3223 #24597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
aevesdocker wants to merge 4 commits into
base: main
Choose a base branch
from
+96 −26
Draft

Engdocs 3223 #24597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aecc630
ENGDOCS-3223
aevesdocker Apr 1, 2026
2b1737f
edit
aevesdocker Apr 1, 2026
fa4968d
SME review fixes
aevesdocker Apr 2, 2026
eede86a
vale
aevesdocker Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/manuals/admin/organization/onboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
73 changes: 56 additions & 17 deletions content/manuals/desktop/setup/install/windows-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,29 @@

_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 |
| 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

> [!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" >}}
Expand Down Expand Up @@ -131,7 +147,11 @@

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. 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.

Check warning on line 150 in content/manuals/desktop/setup/install/windows-install.md

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'select' instead of 'click'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'select' instead of 'click'", "location": {"path": "content/manuals/desktop/setup/install/windows-install.md", "range": {"start": {"line": 150, "column": 11}}}, "severity": "INFO"}

> [!NOTE]
>
>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.

Expand All @@ -143,43 +163,54 @@

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 <user> /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:
Expand Down Expand Up @@ -249,6 +280,8 @@

#### 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=<path>`: Changes the default installation location (`C:\Program Files\Docker\Docker`)
Expand Down Expand Up @@ -293,13 +326,19 @@

### 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
Expand Down
47 changes: 39 additions & 8 deletions content/manuals/desktop/setup/install/windows-permission-requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,28 +12,55 @@ 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.

## 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 **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.

### 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**. When you change one of these settings and select **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.

Expand Down Expand Up @@ -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
Expand Down