Skip to content

freshness: dd setup #26228

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
aevesdocker merged 1 commit into from
Sep 30, 2026
Merged

freshness: dd setup #26228

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
6 changes: 6 additions & 0 deletions content/manuals/desktop/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,12 @@ grid:
description: Provide feedback on Docker Desktop or Docker Desktop features.
icon: chat-bubble-left
link: /desktop/troubleshoot-and-support/feedback/
aliases:
- /desktop/mac/
- /desktop/windows/
- /docker-for-mac/
- /docker-for-windows/
- /desktop/get-started/
---

Docker Desktop is a one-click-install application for your Mac, Linux, or Windows environment
Expand Down
50 changes: 49 additions & 1 deletion content/manuals/desktop/setup/install/linux/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ aliases:
- /desktop/linux/install/
- /desktop/install/linux-install/
- /desktop/install/linux/
- /desktop/linux/
---

> **Docker Desktop terms**
Expand Down Expand Up @@ -143,7 +144,7 @@ To install Docker Desktop successfully, your Linux host must meet the following
- For many Linux distributions, the GNOME environment does not support tray icons. To add support for tray icons, you need to install a GNOME extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/).
- At least 4 GB of RAM.
- Enable configuring ID mapping in user namespaces, see [File sharing](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-enable-file-sharing). Note that for Docker Desktop version 4.35 and later, this is not required anymore.
- Recommended: [Initialize `pass`](/manuals/desktop/setup/sign-in.md#credentials-management-for-linux-users) for credentials management.
- [Initialize `pass`](#signing-in-with-docker-desktop-for-linux) for credentials management.

Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see [Why Docker Desktop for Linux runs a VM](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#why-does-docker-desktop-for-linux-run-a-vm).

Expand Down Expand Up @@ -201,6 +202,53 @@ $ sudo usermod -aG kvm $USER

Sign out and sign back in so that your group membership is re-evaluated.

## Signing in with Docker Desktop for Linux

Docker Desktop for Linux relies on [`pass`](https://www.passwordstore.org/) to store credentials in GPG-encrypted files.
Before signing in to Docker Desktop with your [Docker ID](/accounts/individual/create-account/), you must initialize `pass`.
Docker Desktop displays a warning if `pass` is not configured.

1. Generate a GPG key. You can initialize pass by using a gpg key. To generate a gpg key, run:

``` console
$ gpg --generate-key
```
2. Enter your name and email once prompted.

@akristen akristen Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
2. Enter your name and email once prompted.
1. Enter your name and email once prompted.

lazy ordering tier 1 check on this content


Once confirmed, GPG creates a key pair. Look for the `pub` line that contains your GPG ID, for example:

```text
...
pubrsa3072 2022-03-31 [SC] [expires: 2024-03-30]
3ABCD1234EF56G78
uid Molly <molly@example.com>
```
3. Copy the GPG ID and use it to initialize `pass`. For example

```console
$ pass init 3ABCD1234EF56G78
```

You should see output similar to:

```text
mkdir: created directory '/home/molly/.password-store/'
Password store initialized for <generated_gpg-id_public_key>
```

Once you initialize `pass`, you can sign in and pull your private images.
When Docker CLI or Docker Desktop use credentials, a user prompt may pop up for the password you set during the GPG key generation.

```console
$ docker pull molly/privateimage
Using default tag: latest
latest: Pulling from molly/privateimage
3b9cc81c3203: Pull complete
Digest: sha256:3c6b73ce467f04d4897d7a7439782721fd28ec9bf62ea2ad9e81a5fb7fb3ff96
Status: Downloaded newer image for molly/privateimage:latest
docker.io/molly/privateimage:latest
```

## Using Docker SDKs with Docker Desktop

Docker Desktop for Linux uses a per-user socket instead of the system-wide `/var/run/docker.sock`. Docker SDKs and tools that connect directly to the Docker daemon need the `DOCKER_HOST` environment variable set to connect to Docker Desktop. For configuration details, see [How do I use Docker SDKs with Docker Desktop for Linux?](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-use-docker-sdks-with-docker-desktop-for-linux).
Expand Down
35 changes: 26 additions & 9 deletions content/manuals/desktop/setup/install/mac-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,28 +79,36 @@

1. Download the installer using the download buttons at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md).

2. Double-click `Docker.dmg` to open the installer, then drag the Docker icon to the **Applications** folder. By default, Docker Desktop is installed at `/Applications/Docker.app`.
1. Double-click `Docker.dmg` to open the installer, then drag the Docker icon to the **Applications** folder. By default, Docker Desktop is installed at `/Applications/Docker.app`.

Check warning on line 82 in content/manuals/desktop/setup/install/mac-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/mac-install.md", "range": {"start": {"line": 82, "column": 11}}}, "severity": "INFO"}

3. Double-click `Docker.app` in the **Applications** folder to start Docker.
1. Double-click `Docker.app` in the **Applications** folder to start Docker.

Check warning on line 84 in content/manuals/desktop/setup/install/mac-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/mac-install.md", "range": {"start": {"line": 84, "column": 11}}}, "severity": "INFO"}

4. The Docker menu displays the Docker Subscription Service Agreement.
1. The Docker menu displays the Docker Subscription Service Agreement.

Here’s a summary of the key points:
- Docker Desktop is free for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open source projects.
- Otherwise, it requires a paid subscription for professional use.
- Paid subscriptions are also required for government entities.
- Docker Pro, Team, and Business subscriptions include commercial use of Docker Desktop.

5. Select **Accept** to continue.
1. Select **Accept** to continue.

Note that Docker Desktop won't run if you do not agree to the terms. You can choose to accept the terms at a later date by opening Docker Desktop.

For more information, see [Docker Desktop Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement). It is recommended that you also read the [FAQs](https://www.docker.com/pricing/faq).

6. From the installation window, select either:
- **Use recommended settings (Requires password)**. This lets Docker Desktop automatically set the necessary configuration settings.
- **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, and enable the default Docker socket. With version 4.88.0 and earlier, you can also enable privileged port mapping. See [Settings](/manuals/desktop/settings-and-maintenance/settings.md#advanced), for more information and how to set the location of the Docker CLI tools.
7. Select **Finish**. If you have applied any of the previous configurations that require a password in step 6, enter your password to confirm your choice.
1. Docker Desktop starts. No further configuration is needed and you aren't asked for a password.

Docker Desktop applies a default configuration that requires no privileged access: Docker CLI tools are installed under `$HOME/.docker/bin`, which is added to your `PATH`, and the default Docker socket isn't created. To change either of these, go to **Settings** > **Advanced** after installation. See [Advanced (Mac only)](/manuals/desktop/settings-and-maintenance/settings.md#advanced-mac-only).

> [!NOTE]
>
> With Docker Desktop version 4.88.0 and earlier, these options are presented during installation instead. From the installation window, select either:
>
> - **Use recommended settings (requires password)**. This lets Docker Desktop automatically set the necessary configuration settings.
> - **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping.
>
> Then select **Finish**. If you applied any configuration that requires a password, enter your password to confirm your choice.

### Install from the command line

Expand All @@ -122,11 +130,11 @@

- `--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.
- `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI.
- `--backend=docker-vmm`: Selects the Docker VMM engine at install time. `docker-vmm` is the only supported value on Mac; any other value fails the installation. For more information, see [Virtual Machine Manager](/manuals/desktop/features/vmm.md).

##### Security and access

- `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application
- `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI.
- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by administrators to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md).
- It must be used together with the `--allowed-org=<org name>` flag.
- For example: `--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"`
Expand All @@ -139,6 +147,15 @@
- `--override-proxy-exclude=<hosts/domains>`: Bypasses proxy settings for the hosts and domains. It's a comma-separated list.
- `--override-proxy-pac=<PAC file URL>`: Sets the PAC file URL. This setting takes effect only when using `manual` proxy mode.
- `--override-proxy-embedded-pac=<PAC script>`: Specifies an embedded PAC (Proxy Auto-Config) script. This setting takes effect only when using `manual` proxy mode and has precedence over the `--override-proxy-pac` flag.
- `--proxy-enable-kerberosntlm`: Enables Kerberos and NTLM proxy authentication. If you are enabling this, ensure your proxy server is properly configured for Kerberos/NTLM authentication.

> [!IMPORTANT]
>
> Addresses passed to `--override-proxy-http` and `--override-proxy-https` are validated during installation, and an invalid value fails the install:
>
> - The address must include a port, for example `http://proxy.example.com:3128`. An address with no port is rejected.
> - The address must not include credentials. Use `--proxy-enable-kerberosntlm` for authenticated proxies.
> - If you omit the scheme, `http://` is added for you. `http://`, `https://`, and `socks5://` are accepted.

###### Example of specifying PAC file

Expand Down
15 changes: 7 additions & 8 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 @@ -144,21 +144,21 @@

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. The installer will ask which installation mode you prefer. Choosing per-user installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and requires no administrator privileges. Choosing all users will prompt for elevation.
1. 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. Choosing all users will prompt for elevation.

Check warning on line 147 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": 147, "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, select your backend on the Configuration page: **Use WSL 2 instead of Hyper-V** for WSL 2, or leave it unselected for Hyper-V. You can switch to Docker VMM after installation from **Settings** > **General**.
1. When prompted, select your backend on the Configuration page: **Use WSL 2 instead of Hyper-V** for WSL 2, or leave it unselected for Hyper-V. You can switch to Docker VMM after installation from **Settings** > **General**.

On systems that support only one backend, Docker Desktop automatically selects the available option.

4. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation.
1. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation.

5. When the installation is successful, select **Close** to complete the installation process.
1. When the installation is successful, select **Close** to complete the installation process.

6. [Start Docker Desktop](#start-docker-desktop).
1. [Start Docker Desktop](#start-docker-desktop).

### Install from the command line

Expand Down Expand Up @@ -283,12 +283,11 @@

#### 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`)
- `--backend=<backend name>`: Selects the default backend to use for Docker Desktop, `hyper-v`, `windows` or `wsl-2` (default)
- `--backend=<backend name>`: Selects the default backend to use for Docker Desktop: `wsl-2` (default), `hyper-v`, `windows`, or `docker-vmm`.
- `--always-run-service`: After installation completes, starts `com.docker.service` and sets the service startup type to Automatic. This circumvents the need for administrator privileges, which are otherwise necessary to start `com.docker.service`. `com.docker.service` is required by Windows containers and Hyper-V backend.

#### Security and access control
Expand All @@ -297,7 +296,7 @@
- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md).
- It must be used together with the `--allowed-org=<org name>` flag.
- For example:`--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"`
- `--no-windows-containers`: Disables the Windows containers integration. This can improve security. For more information, see [Windows containers](/manuals/desktop/setup/install/windows-permission-requirements.md#windows-containers).
- `--no-windows-containers`: Disables the Windows containers integration. This can improve security. Can't be combined with `--backend=windows`. For more information, see [Windows containers](/manuals/desktop/setup/install/windows-permission-requirements.md#windows-containers).

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

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Docker.Spacing] '  ' should have one space.

Raw Output:
{"message": "[Docker.Spacing] '  ' should have one space.", "location": {"path": "content/manuals/desktop/setup/install/windows-install.md", "range": {"start": {"line": 299, "column": 101}}}, "severity": "ERROR"}

#### Proxy configuration

Expand Down
2 changes: 1 addition & 1 deletion 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 @@ -113,7 +113,7 @@ isolated from the Docker daemon and other services running inside the VM.
>
> 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.
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
Loading
Loading