Configure Settings Management with a JSON file

This page explains how to use an admin-settings.json file to configure and enforce Docker Desktop settings. Use this method to standardize Docker Desktop environments in your organization.

Prerequisites

• Enforce sign-in to ensure all users authenticate with your organization.
• A Docker Business subscription is required.

Docker Desktop only applies settings from the admin-settings.json file if both authentication and Docker Business license checks succeed.

Important

If a user isn't signed in or isn't part of a Docker Business organization, the settings file is ignored.

Limitation

• The admin-settings.json file doesn't work in air-gapped or offline environments.
• The file is not compatible with environments that restrict authentication with Docker Hub.

Step one: Create the settings file

You can:

• Use the --admin-settings installer flag to auto-generate the file. See:
  • macOS install guide
  • Windows install guide
• Or create it manually and place it in the following locations:
  • Mac: /Library/Application\ Support/com.docker.docker/admin-settings.json
  • Windows: C:\ProgramData\DockerDesktop\admin-settings.json
  • Linux: /usr/share/docker-desktop/admin-settings.json

Important

Place the file in a protected directory to prevent modification. Use MDM tools like Jamf to distribute it at scale.

Step two: Define settings

Tip

For a complete list of available settings, their supported platforms, and which configuration methods they work with, see the Settings reference.

The admin-settings.json file uses structured keys to define what can be configured and whether the values are enforced.

Each setting supports the locked field. When locked is set to true, users can't change that value in Docker Desktop, the CLI, or config files. When locked is set to false, the value acts like a default suggestion and users can still update it.

Settings where locked is set to false are ignored on existing installs if a user has already customized that value in settings-store.json, settings.json, or daemon.json.

Note

Some settings are platform-specific or require a minimum Docker Desktop version. See the Settings reference for details.

Example settings file

The following file is an example admin-settings.json file. For a full list of configurable settings for the admin-settings.json file, see admin-settings.json configurations.

{   "configurationFileVersion": 2,   "exposeDockerAPIOnTCP2375": {     "locked": true,     "value": false   },   "proxy": {     "locked": true,     "mode": "system",     "http": "",     "https": "",     "exclude": [],     "windowsDockerdPort": 65000,     "enableKerberosNtlm": false   },   "containersProxy": {     "locked": true,     "mode": "manual",     "http": "",     "https": "",     "exclude": [],     "pac":"",     "transparentPorts": ""   },   "enhancedContainerIsolation": {     "locked": true,     "value": true,     "dockerSocketMount": {       "imageList": {         "images": [           "docker.io/localstack/localstack:*",           "docker.io/testcontainers/ryuk:*"         ]       },       "commandList": {         "type": "deny",         "commands": ["push"]       }     }   },   "linuxVM": {     "wslEngineEnabled": {       "locked": false,       "value": false     },     "dockerDaemonOptions": {       "locked": false,       "value":"{\"debug\": false}"     },     "vpnkitCIDR": {       "locked": false,       "value":"192.168.65.0/24"     }   },   "kubernetes": {      "locked": false,      "enabled": false,      "showSystemContainers": false,      "imagesRepository": ""   },   "windowsContainers": {     "dockerDaemonOptions": {       "locked": false,       "value":"{\"debug\": false}"     }   },   "disableUpdate": {     "locked": false,     "value": false   },   "analyticsEnabled": {     "locked": false,     "value": true   },   "extensionsEnabled": {     "locked": true,     "value": false   },   "scout": {     "locked": false,     "sbomIndexing": true,     "useBackgroundIndexing": true   },   "allowExperimentalFeatures": {     "locked": false,     "value": false   },   "allowBetaFeatures": {     "locked": false,     "value": false   },   "blockDockerLoad": {     "locked": false,     "value": true   },   "filesharingAllowedDirectories": [     {       "path": "$HOME",       "sharedByDefault": true     },     {       "path":"$TMP",       "sharedByDefault": false     }   ],   "useVirtualizationFrameworkVirtioFS": {     "locked": true,     "value": true   },   "useVirtualizationFrameworkRosetta": {     "locked": true,     "value": true   },   "useGrpcfuse": {     "locked": true,     "value": true   },   "displayedOnboarding": {     "locked": true,     "value": true   },   "desktopTerminalEnabled": {     "locked": false,     "value": false   } }

Step three: Restart and apply settings

Settings apply after Docker Desktop is restarted and the user is signed in.

• New installs: Launch Docker Desktop and sign in.
• Existing installs: Quit Docker Desktop fully and relaunch it.

Important

Restarting Docker Desktop from the menu isn't enough. It must be fully quit and reopened.

admin-settings.json configurations

General

File sharing and emulation

Docker Scout

Proxy

Container proxy

Linux VM

Windows containers

Note

This setting is not available to configure via the Docker Admin Console.

Kubernetes

Note

When using the imagesRepository setting and Enhanced Container Isolation (ECI), add the following images to the ECI Docker socket mount image list:

• [imagesRepository]/desktop-cloud-provider-kind:*
• [imagesRepository]/desktop-containerd-registry-mirror:*

These containers mount the Docker socket, so you must add the images to the ECI images list. If not, ECI will block the mount and Kubernetes won't start.

Features in development

Enhanced Container Isolation