docker · aevesdocker · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026 · akristen
@@ -19,10 +19,12 @@ When users don't sign in as organization members, they miss out on subscription
 
 You can enforce sign-in using several methods, depending on your setup:
 
-- [Registry key method (Windows only)](methods.md#registry-key-method-windows-only)
-- [Configuration profiles method (Mac only)](methods.md#configuration-profiles-method-mac-only)
-- [`.plist` method (Mac only)](methods.md#plist-method-mac-only)
-- [`registry.json` method (All)](methods.md#registryjson-method-all)
+- [Registry key method (Windows only)](methods.md#windows-registry-key-method)
+- [Configuration profiles method (Mac only)](methods.md#mac-configuration-profiles-method-recommended)
+- [`.plist` method (Mac only)](methods.md#mac-plist-file-method)
+- [`registry.json` method (all platforms)](methods.md#all-platforms-registryjson-method)
+
+Deploying a `admin-settings.json` file with [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) also enforces sign-in. See [Settings Management and sign-in enforcement](methods.md#settings-management-and-sign-in-enforcement).
 
 This page provides an overview of how sign-in enforcement works.
 
@@ -31,23 +33,45 @@ This page provides an overview of how sign-in enforcement works.
 When Docker Desktop detects a registry key, configuration profile, `.plist` file, or
 `registry.json` file:
 
-- A **Sign in required!** prompt appears, requiring users to sign
-  in as organization members to use Docker Desktop.
+- A **Sign in using your work email address** prompt appears, requiring users to
+  sign in as organization members to use Docker Desktop. The prompt states which
+  organizations are required and which method enforces it.
 - If users sign in with accounts that aren't organization members, they're
-  automatically signed out and can't use Docker Desktop. They can select **Sign in**
-  to try again with a different account.
+  automatically signed out and can't use Docker Desktop. The prompt changes to
+  **You have been signed out** and explains why. They can sign in again with a
+  different account.
 - When users sign in with organization member accounts, they can use Docker
   Desktop normally.
-- When users sign out, the **Sign in required!** prompt reappears and they can
+- When users sign out, the sign-in prompt reappears and they can
   no longer use Docker Desktop unless they sign back in.
 
-> [!NOTE]
+### Impact on the Docker CLI
+
+Sign-in enforcement also blocks the Docker CLI. While the sign-in prompt is
+showing, Docker Desktop's API proxy rejects almost every request with an
+explanation at the terminal, for example:
+
+```text
+Sign in to continue using Docker Desktop. Membership in the [myorg] organization
+is required. Sign in enforced by your administrators (via registry.json).
+```
+
+- `docker run`, `docker pull`, `docker build`, `docker ps`, and other commands
+  that reach the engine fail until the user signs in.
+- `docker version`, `docker info`, and `docker login` continue to work, so users
+  can sign in from the CLI.
+
+> [!IMPORTANT]
 >
-> Enforcing sign-in for Docker Desktop doesn't affect Docker CLI access. CLI access is only restricted for organizations that enforce single sign-on (SSO).
+> Make sure you plan for blocking the Docker CLI before you roll out enforcement. Any scripted or CI use of the
+> Docker CLI on an enforced machine stops working until that machine's user signs
+> in as an organization member.
+
+Sign-in enforcement is separate from [SSO enforcement](#enforcing-sign-in-versus-enforcing-single-sign-on-sso), which governs how users authenticate as opposed to whether they must authenticate.
 
 ### Impact on already-signed-in users
 
-When enforcement is first deployed, users who are already running Docker Desktop are not immediately affected. Docker Desktop only re-evaluates enforcement on restart.
+When enforcement is first deployed, users who are already running Docker Desktop are not immediately affected. Docker Desktop re-evaluates enforcement when it starts, and when a user signs in or out. It doesn't poll for new configuration while running, so a newly deployed registry key, configuration profile, `.plist`, or `registry.json` file takes effect on the next restart.
 
 On the next Docker Desktop restart:
 

@@ -47,6 +47,16 @@ To configure the registry key method manually:
 1. Restart Docker Desktop.
 1. Verify the **Sign in required!** prompt appears in Docker Desktop.
 
+You can also create this key at install time with the MSI installer's
+`ALLOWEDORG` property, which accepts multiple organizations separated by
+semicolons:
+
+```powershell
+msiexec /i "DockerDesktop.msi" /quiet /norestart ALLOWEDORG="myorg1;myorg2"
+```
+
+For more information, see [MSI installer](/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md#configuration-options).
+
 {{< /tab >}}
 {{< tab name="Group Policy deployment" >}}
 
@@ -84,8 +94,15 @@ The payload is a dictionary of key-values. Docker Desktop supports the following
 - `overrideProxyPAC`: Sets the file path where the PAC file is located. It has precedence over the remote PAC file on the selected proxy.
 - `overrideProxyEmbeddedPAC`: Sets the content of an in-memory PAC file. It has precedence over `overrideProxyPAC`.
 
-Overriding at least one of the proxy settings via Configuration profiles will automatically lock the settings as they're managed by Mac.
+> [!IMPORTANT]
+>
+> `allowedOrgs` must be a `<string>`, not an `<array>`. Docker Desktop only reads
+> string values from a configuration profile, so an array is silently ignored and
+> no enforcement happens. This differs from the
+> [`.plist` method](#mac-plist-file-method), which does use an array.
 
+Setting at least one of the proxy keys puts Docker Desktop's proxy into manual
+mode and locks the proxy settings, so developers can't change them.
 
 1. Create a file named `docker.mobileconfig` and include the following content:
    ```xml
@@ -179,7 +196,7 @@ Some MDM solutions let you specify the payload as a plain dictionary of key-valu
    ```
 1. Set file permissions to prevent editing by non-administrator users.
 1. Restart Docker Desktop.
-1. Verify the `Sign in required!` prompt appears in Docker Desktop.
+1. Verify the **Sign in using your work email address** prompt appears in Docker Desktop.
 
 {{< /tab >}}
 {{< tab name="Shell script deployment" >}}
@@ -211,11 +228,11 @@ The registry.json method works across all platforms and offers flexible deployme
 
 ### File locations
 
-Create the `registry.json` file (UTF-8 without BOM) at the appropriate location:
+Create the `registry.json` file (UTF-8) at the appropriate location:
 
 | Platform | Location |
 | --- | --- |
-| Windows | `/ProgramData/DockerDesktop/registry.json` |
+| Windows | `%ProgramData%\DockerDesktop\registry.json` |
 | Mac | `/Library/Application Support/com.docker.docker/registry.json` |
 | Linux | `/usr/share/docker-desktop/registry/registry.json` |
 
@@ -234,12 +251,10 @@ Create the `registry.json` file (UTF-8 without BOM) at the appropriate location:
       ```
 1. Set file permissions to prevent user editing.
 1. Restart Docker Desktop.
-1. Verify the `Sign in required!` prompt appears in Docker Desktop.
+1. Verify the **Sign in using your work email address** prompt appears in Docker Desktop.
 
-> [!TIP]
->
-> If users have issues starting Docker Desktop after enforcing sign-in,
-> they may need to update to the latest version.
+If users have issues starting Docker Desktop after enforcing sign-in,
+they may need to update to the latest version.
 
 {{< /tab >}}
 {{< tab name="Command line setup" >}}
@@ -271,17 +286,27 @@ Create the registry.json file during Docker Desktop installation:
 
 #### Windows
 
+`--allowed-org` is a flag on the EXE installer. If you deploy with the MSI
+installer, use the `ALLOWEDORG` property instead, which creates the
+[registry key](#windows-registry-key-method).
+
 ```shell
 # PowerShell
 Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg'
 
 # Command Prompt
 "Docker Desktop Installer.exe" install --allowed-org=myorg1
 ```
+The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation.
 
-> [!NOTE]
+> [!IMPORTANT]
 >
-> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation.
+> With Docker Desktop version 4.83 and later, `--allowed-org` can't be combined
+> with `--user`, and it can't be used for a Microsoft Store installation. Both
+> are per-user installations and the installer rejects the combination. This
+> matters because the Windows installer selects a per-user installation by
+> default from version 4.83. For per-user installations, configure the
+> `registry.json` file after installation.
 
 #### Mac
 
@@ -290,28 +315,60 @@ sudo hdiutil attach Docker.dmg
 sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg
 sudo hdiutil detach /Volumes/Docker
 ```
-> [!NOTE]
->
-> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation.
+
+The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation.
 
 {{< /tab >}}
 {{< /tabs >}}
 
 ## Method precedence
 
-When multiple configuration methods exist on the same system, Docker Desktop uses this precedence order:
+When more than one configuration method exists on the same machine, Docker
+Desktop evaluates them in order and stops at the first one that's configured.
+The order depends on the platform.
+
+| Platform | Precedence order |
+|:---------|:-----------------|
+| Windows | 1. Registry key<br>2. `registry.json`<br>3. `admin-settings.json` |
+| Mac | 1. Configuration profile<br>2. `desktop.plist`<br>3. `registry.json`<br>4. `admin-settings.json` |
+| Linux | 1. `registry.json`<br>2. `admin-settings.json` |
+
+Lower-precedence methods are not consulted once a higher one applies. For
+example, on a Mac with both a configuration profile and a `registry.json` file,
+only the organizations in the configuration profile are enforced.
+
+## Settings Management and sign-in enforcement
 
-1. Registry key (Windows only)
-1. Configuration profiles (Mac only)
-1. plist file (Mac only)
-1. registry.json file
+Deploying an `admin-settings.json` file enforces sign-in on its own, even if the
+file contains no organization list. Users who aren't on a Docker Business
+subscription see the sign-in prompt, and the Docker Engine is held until they
+sign in.
+
+This differs from the four methods above in two ways:
+
+- It doesn't restrict sign-in to particular organizations, so any Docker account
+  satisfies it. Combine it with one of the methods above if you need organization
+  membership enforced.
+- It's the lowest-precedence method, so any of the methods above overrides it.
+
+If you use [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md), account for this when planning your rollout: developers who are signed out will be prompted to sign in as soon as the file reaches their machine and Docker Desktop restarts.
 
 ## Troubleshoot sign-in enforcement
 
 If sign-in enforcement doesn't work:
 
 - Verify file locations and permissions
-- Check that organization names use lowercase letters
-- Restart Docker Desktop or reboot the system
+- Check that organization names use lowercase letters and match your Docker Hub
+  organization name exactly. Matching is case-sensitive, so a mismatch signs out
+  every user
+- Check for stray whitespace in the value. In the Windows registry key, put each
+  organization on its own line rather than separating them with spaces or commas
+- Check whether a higher-precedence method is in effect. See
+  [Method precedence](#method-precedence)
+- Restart Docker Desktop or reboot the system. Docker Desktop doesn't pick up new
+  configuration while running
 - Confirm users are members of the specified organizations
 - Update Docker Desktop to the latest version
+
+If enforcement works but developers report that the Docker CLI stopped working,
+that's expected. See [Impact on the Docker CLI](_index.md#impact-on-the-docker-cli).
@@ -33,6 +33,8 @@
  - /enterprise/enterprise-deployment/
 ---
 
-Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions like Intune or Jamf, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, macOS, and Linux systems.
+Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. 
+
+Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, Mac, and Linux systems.
 
 {{< grid >}}
@@ -8,6 +8,12 @@ aliases:
  - /enterprise/enterprise-deployment/dev-box/
 ---
 
+> [!IMPORTANT]
+>
+> Microsoft has announced the retirement of Microsoft Dev Box. The service entered its closing-down period on 14 September 2026 and retires fully at 17:00 UTC on 18 September 2028. Microsoft recommends transitioning to Windows 365 or another solution. See the [Microsoft Dev Box retirement guide](https://learn.microsoft.com/en-us/azure/dev-box/dev-box-retirement-guide).
+>
+> To deploy Docker Desktop on Windows 365 Cloud PCs or other managed Windows machines, use the [MSI installer](msi-install-and-configure.md) with [Intune](use-intune.md).
+
 Docker Desktop is available as a pre-configured image in the Microsoft Azure Marketplace for use with Microsoft Dev Box, allowing developers to quickly set up consistent development environments in the cloud.
 
 Microsoft Dev Box provides cloud-based, pre-configured developer workstations that allow you to code, build, and test applications without configuring a local development environment. The Docker Desktop image for Microsoft Dev Box comes with Docker Desktop and its dependencies pre-installed, giving you a ready-to-use containerized development environment.
@@ -34,17 +40,17 @@ Microsoft Dev Box provides cloud-based, pre-configured developer workstations th
 ### Set up Docker Desktop in Dev Box
 
 1. Navigate to the [Docker Desktop for Microsoft Dev Box](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/dockerinc1694120899427.devbox_azuremachine?tab=Overview) listing in Azure Marketplace.
-2. Select **Get It Now** to add the virtual machine image to your subscription.
-3. Follow the Azure workflow to complete the setup.
-4. Use the image to create VMs, assign to Dev Centers, or create Dev Box Pools according to your organization's setup.
+1. Select **Get It Now** to add the virtual machine image to your subscription.
+1. Follow the Azure workflow to complete the setup.
+1. Use the image to create VMs, assign to Dev Centers, or create Dev Box Pools according to your organization's setup.
 
 ### Activate Docker Desktop
 
 Once your Dev Box is provisioned with the Docker Desktop image:
 
 1. Start your Dev Box instance.
-2. Launch Docker Desktop.
-3. Sign in with your Docker ID.
+1. Launch Docker Desktop.
+1. Sign in with your Docker ID.
 
 ## Support
 

@@ -15,20 +15,71 @@ Common questions about installing Docker Desktop using the MSI installer.
 
 ### What happens to user data if they have an older Docker Desktop installation (i.e. `.exe`)?
 
-Users must [uninstall](/manuals/desktop/uninstall.md) older `.exe` installations before using the new MSI version. The `.exe` installer includes a `-keep-data` flag that removes Docker Desktop while preserving underlying resources such as the container VMs:
+Users must [uninstall](/manuals/desktop/uninstall.md) older `.exe` installations before using the new MSI version. The `.exe` installer includes a `--keep-data` flag that removes Docker Desktop while preserving underlying resources such as the container VMs:
 
 ```powershell
 # For all-user installations
-& 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall -keep-data
+& 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall --keep-data
 
 # For per-user installations
-& '%LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe' uninstall -keep-data
+& '%LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe' uninstall --keep-data
 
 ```
 
+For all-users installations, you can have the MSI do this for you with the `REMOVEEXISTINGINSTALL` property, described in the next answer.
+
+### What happens if the user's machine has an older `.exe` installation?
+
 ### What happens if the user's machine has an older `.exe` installation?
 
-The MSI installer detects older `.exe` installations and blocks the installation until the previous version is uninstalled. It prompts the user to uninstall their current/old version first, before retrying to install the MSI version.
+The MSI installer detects existing `.exe` installations and, by default, blocks the installation. How you resolve it depends on whether the `.exe` was installed for all users or for a single user.
+
+#### All-users `.exe` installation
+
+The installation stops with:
+
+```text
+You need to uninstall the previous Docker Desktop version in order to use the MSI installer.
+```
+
+Either uninstall it first with `--keep-data` as described in the previous answer, or let the MSI do it by setting `REMOVEEXISTINGINSTALL=1`:
+
+```powershell
+msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart REMOVEEXISTINGINSTALL=1
+```
+
+This runs the existing uninstaller with `--keep-data`, so settings and container data are preserved. `REMOVEEXISTINGINSTALL` defaults to `0` and is available with Docker Desktop version 4.30 and later.
+
+#### Per-user `.exe` installation
+
+Available with Docker Desktop version 4.84 and later, the installation stops with:
+
+```text
+Docker Desktop is installed per-user for one or more accounts on this machine: <usernames>.
+Please have each affected user uninstall Docker Desktop first before running the MSI installer.
+```
+
+`REMOVEEXISTINGINSTALL` doesn't help here. The MSI runs with machine-wide privileges and can't reliably uninstall software installed under another user's profile, so each listed user must uninstall Docker Desktop themselves before the MSI can proceed.
+
+With Docker Desktop version 4.83 and earlier, the MSI doesn't detect per-user installations.
+
+> [!NOTE]
+>
+> Per-user installations became more common with Docker Desktop version 4.83, when the EXE installer started selecting a per-user installation by default. Expect to encounter them on machines where developers installed Docker Desktop themselves.
+
+### Can I install the MSI per-user?
+
+No. The MSI installer only supports all-users installations.
+
+Available with Docker Desktop version 4.92 and later, passing `MSIINSTALLPERUSER` fails with:
+
+```text
+Docker Desktop does not support per-user installation with the MSI installer.
+```
+
+With Docker Desktop version 4.91 and earlier, the MSI accepts `MSIINSTALLPERUSER` but produces an installation that later updates can't upgrade.
+
+Use the EXE installer with the `--user` flag if you need a per-user installation.
 
 ### My installation failed, how do I find out what happened?