Skip to content

Update permission requirements for Docker Desktop on Windows #22863

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

Merged
merged 4 commits into from
Jun 20, 2025
Merged

Update permission requirements for Docker Desktop on Windows #22863

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
06d57a2
[windows install] update docker-users guidance
chelnak Jun 18, 2025
62b35be
[windows msi] update docker-users guidance
chelnak Jun 18, 2025
eb59b5e
[windows] update permission requirements
chelnak Jun 18, 2025
09053ef
Apply suggestions from code review
aevesdocker Jun 20, 2025
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 ...anuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
7. Follow the instructions on the installation wizard to authorize the installer and proceed with the install.
8. When the installation is successful, select **Finish** to complete the installation process.

If your administrator account is different from your user account, you must add the user to the **docker-users** group:
If your administrator account is different from 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:

Check failure on line 37 in content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Capitalization] Please capitalize Docker.

Raw Output:
{"message": "[Docker.Capitalization] Please capitalize Docker.", "location": {"path": "content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md", "range": {"start": {"line": 37, "column": 1}}}, "severity": "ERROR"}
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.
Expand Down
7 changes: 5 additions & 2 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 @@ -180,7 +180,8 @@

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

Check failure on line 183 in content/manuals/desktop/setup/install/windows-install.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Capitalization] Please capitalize Docker.

Raw Output:
{"message": "[Docker.Capitalization] Please capitalize Docker.", "location": {"path": "content/manuals/desktop/setup/install/windows-install.md", "range": {"start": {"line": 183, "column": 1}}}, "severity": "ERROR"}

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.
Expand Down Expand Up @@ -218,7 +219,9 @@
> Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--accept-license'
> ```

If your admin account is different to your user account, you must add the user to the **docker-users** group:
If your admin 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.

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'administrator' instead of 'admin'

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

Check failure on line 222 in content/manuals/desktop/setup/install/windows-install.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Capitalization] Please capitalize Docker.

Raw Output:
{"message": "[Docker.Capitalization] Please capitalize Docker.", "location": {"path": "content/manuals/desktop/setup/install/windows-install.md", "range": {"start": {"line": 222, "column": 1}}}, "severity": "ERROR"}

```powershell
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like a stray code fence here

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤦 fixing

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was JUST too late; saw you merged when I submitted 😅😆


```console
$ net localgroup docker-users <user> /add
Expand Down
15 changes: 13 additions & 2 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 @@ -18,12 +18,23 @@

## 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, provided you are members of the `docker-users` group. 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 Docker Desktop.
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.

Check warning on line 21 in content/manuals/desktop/setup/install/windows-permission-requirements.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.Acronyms] 'UAC' has no definition.

Raw Output:
{"message": "[Docker.Acronyms] 'UAC' has no definition.", "location": {"path": "content/manuals/desktop/setup/install/windows-permission-requirements.md", "range": {"start": {"line": 21, "column": 159}}}, "severity": "WARNING"}

The reason for this approach is that 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.
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.

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.

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


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.

The service performs the following functionalities:
Expand Down