docs: address issue #23308 (#24115)

github-actions[bot] · aevesdocker · web-flow · commit f5240e4220aa · 2026-02-12T11:03:06.000Z
## Summary Added documentation for DOCKER_HOST requirement when using Docker SDKs with Docker Desktop for Linux. ## Changes - Added "Using Docker SDKs with Docker Desktop" section to Linux install docs explaining why SDKs need DOCKER_HOST set and providing configuration commands - Added FAQ entry "How do I use Docker SDKs with Docker Desktop for Linux?" with troubleshooting steps - Added note in SDK reference docs alerting Docker Desktop for Linux users to set DOCKER_HOST before using SDKs Fixes #23308 --- 🤖 Generated with [cagent](https://github.com/docker/cagent) --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: aevesdocker <allie.sadler@docker.com>
diff --git a/content/manuals/desktop/setup/install/linux/_index.md b/content/manuals/desktop/setup/install/linux/_index.md
@@ -1,16 +1,18 @@
 ---
-description: Install Docker on Linux with ease using our step-by-step installation
+description:
+  Install Docker on Linux with ease using our step-by-step installation
   guide covering system requirements, supported platforms, and where to go next.
-keywords: linux, docker linux install, docker linux, linux docker installation, docker
+keywords:
+  linux, docker linux install, docker linux, linux docker installation, docker
   for linux, docker desktop for linux, installing docker on linux, docker download
   linux, how to install docker on linux, linux vs docker engine, switch docker contexts
 title: Install Docker Desktop on Linux
 linkTitle: Linux
 weight: 60
 aliases:
-- /desktop/linux/install/
-- /desktop/install/linux-install/
-- /desktop/install/linux/
+  - /desktop/linux/install/
+  - /desktop/install/linux-install/
+  - /desktop/install/linux/
 ---
 
 > **Docker Desktop terms**
@@ -23,9 +25,9 @@ This page contains information about general system requirements, supported plat
 
 > [!IMPORTANT]
 >
->Docker Desktop on Linux runs a Virtual Machine (VM) which creates and uses a custom docker context, `desktop-linux`, on startup. 
+> Docker Desktop on Linux runs a Virtual Machine (VM) which creates and uses a custom docker context, `desktop-linux`, on startup.
 >
->This means images and containers deployed on the Linux Docker Engine (before installation) are not available in Docker Desktop for Linux. 
+> This means images and containers deployed on the Linux Docker Engine (before installation) are not available in Docker Desktop for Linux.
 >
 > {{< accordion title=" Docker Desktop vs Docker Engine: What's the difference?" >}}
 
@@ -35,7 +37,7 @@ This page contains information about general system requirements, supported plat
 
 Docker Desktop for Linux provides a user-friendly graphical interface that simplifies the management of containers and services. It includes Docker Engine as this is the core technology that powers Docker containers. Docker Desktop for Linux also comes with additional features like Docker Scout and Docker Extensions.
 
-#### Installing Docker Desktop and Docker Engine
+### Installing Docker Desktop and Docker Engine
 
 Docker Desktop for Linux and Docker Engine can be installed side-by-side on the
 same machine. Docker Desktop for Linux stores containers and images in an isolated
@@ -88,7 +90,7 @@ machine. The current context is indicated with an asterisk (`*`).
 $ docker context ls
 NAME            DESCRIPTION                               DOCKER ENDPOINT                                  ...
 default *       Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                      ...
-desktop-linux                                             unix:///home/<user>/.docker/desktop/docker.sock  ...        
+desktop-linux                                             unix:///home/<user>/.docker/desktop/docker.sock  ...
 ```
 
 If you have both Docker Desktop and Docker Engine installed on the same machine,
@@ -101,14 +103,15 @@ $ docker context use default
 default
 Current context is now "default"
 ```
-  
+
 And use the `desktop-linux` context to interact with Docker Desktop:
- 
+
 ```console
 $ docker context use desktop-linux
 desktop-linux
 Current context is now "desktop-linux"
-``` 
+```
+
 Refer to the [Docker Context documentation](/manuals/engine/manage-resources/contexts.md) for more details.
 {{< /accordion >}}
 
@@ -117,13 +120,12 @@ Refer to the [Docker Context documentation](/manuals/engine/manage-resources/con
 Docker provides `.deb` and `.rpm` packages for the following Linux distributions
 and architectures:
 
-| Platform                | x86_64 / amd64          | 
-|:------------------------|:-----------------------:|
-| [Ubuntu](ubuntu.md)                         | ✅  |
-| [Debian](debian.md)                         | ✅  |
-| [Red Hat Enterprise Linux (RHEL)](rhel.md)  | ✅  |
-| [Fedora](fedora.md)                         | ✅  |
-
+| Platform                                   | x86_64 / amd64 |
+| :----------------------------------------- | :------------: |
+| [Ubuntu](ubuntu.md)                        |       ✅       |
+| [Debian](debian.md)                        |       ✅       |
+| [Red Hat Enterprise Linux (RHEL)](rhel.md) |       ✅       |
+| [Fedora](fedora.md)                        |       ✅       |
 
 An experimental package is available for [Arch](archlinux.md)-based distributions. Docker has not tested or verified the installation.
 
@@ -151,7 +153,6 @@ Docker Desktop for Linux runs a Virtual Machine (VM). For more information on wh
 
 ### KVM virtualization support
 
-
 Docker Desktop runs a VM that requires [KVM support](https://www.linux-kvm.org).
 
 The `kvm` module should load automatically if the host has virtualization support. To load the module manually, run:
@@ -186,7 +187,6 @@ irqbypass              16384  1 kvm
 
 #### Set up KVM device user permissions
 
-
 To check ownership of `/dev/kvm`, run :
 
 ```console
@@ -201,13 +201,15 @@ $ sudo usermod -aG kvm $USER
 
 Sign out and sign back in so that your group membership is re-evaluated.
 
-## Where to go next
+## Using Docker SDKs with Docker Desktop
 
-- Install Docker Desktop for Linux for your specific Linux distribution:
-   - [Install on Ubuntu](ubuntu.md)
-   - [Install on Debian](debian.md)
-   - [Install on Red Hat Enterprise Linux (RHEL)](rhel.md)
-   - [Install on Fedora](fedora.md)
-   - [Install on Arch](archlinux.md)
+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).
 
+## Where to go next
 
+- Install Docker Desktop for Linux for your specific Linux distribution:
+  - [Install on Ubuntu](ubuntu.md)
+  - [Install on Debian](debian.md)
+  - [Install on Red Hat Enterprise Linux (RHEL)](rhel.md)
+  - [Install on Fedora](fedora.md)
+  - [Install on Arch](archlinux.md)
diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/general.md b/content/manuals/desktop/troubleshoot-and-support/faqs/general.md
@@ -54,6 +54,8 @@ Docker Desktop Windows users can connect to the Docker Engine through a **named
 
 For details, see [Docker Engine API](/reference/api/engine/_index.md).
 
+See the [Linux FAQs](linuxfaqs.md) for Linux specific setup. 
+
 ### How do I connect from a container to a service on the host?
 
 The host has a changing IP address, or none if you have no network access.
diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md
@@ -5,8 +5,8 @@ title: FAQs for Docker Desktop for Linux
 linkTitle: Linux
 tags: [FAQ]
 aliases:
-- /desktop/linux/space/
-- /desktop/faqs/linuxfaqs/
+  - /desktop/linux/space/
+  - /desktop/faqs/linuxfaqs/
 weight: 40
 ---
 
@@ -16,32 +16,32 @@ Docker Desktop for Linux runs a Virtual Machine (VM) for the following reasons:
 
 1. To ensure that Docker Desktop provides a consistent experience across platforms.
 
-    During research, the most frequently cited reason for users wanting Docker Desktop for Linux was to ensure a consistent Docker Desktop
-    experience with feature parity across all major operating systems. Utilizing
-    a VM ensures that the Docker Desktop experience for Linux users will closely
-    match that of Windows and macOS.
+   During research, the most frequently cited reason for users wanting Docker Desktop for Linux was to ensure a consistent Docker Desktop
+   experience with feature parity across all major operating systems. Utilizing
+   a VM ensures that the Docker Desktop experience for Linux users will closely
+   match that of Windows and macOS.
 
 2. To make use of new kernel features.
 
-    Sometimes we want to make use of new operating system features. Because we control the kernel and the OS inside the VM, we can roll these out to all users immediately, even to users who are intentionally sticking on an LTS version of their machine OS.
+   Because Docker controls the kernel and the OS inside the VM, Docker can roll these out to all users immediately, even to users who are intentionally sticking on an LTS version of their machine OS.
 
 3. To enhance security.
 
-    Container image vulnerabilities pose a security risk for the host environment. There is a large number of unofficial images that are not guaranteed to be verified for known vulnerabilities. Malicious users can push images to public registries and use different methods to trick users into pulling and running them. The VM approach mitigates this threat as any malware that gains root privileges is restricted to the VM environment without access to the host.
+   Container image vulnerabilities pose a security risk for the host environment. There is a large number of unofficial images that are not guaranteed to be verified for known vulnerabilities. Malicious users can push images to public registries and use different methods to trick users into pulling and running them. The VM approach mitigates this threat as any malware that gains root privileges is restricted to the VM environment without access to the host.
 
-    Why not run rootless Docker? Although this has the benefit of superficially limiting access to the root user so everything looks safer in "top", it allows unprivileged users to gain `CAP_SYS_ADMIN` in their own user namespace and access kernel APIs which are not expecting to be used by unprivileged users, resulting in [vulnerabilities](https://www.openwall.com/lists/oss-security/2022/01/18/7).
+   Why not run rootless Docker? Although this has the benefit of superficially limiting access to the root user so everything looks safer in "top", it allows unprivileged users to gain `CAP_SYS_ADMIN` in their own user namespace and access kernel APIs which are not expecting to be used by unprivileged users, resulting in [vulnerabilities](https://www.openwall.com/lists/oss-security/2022/01/18/7).
 
 4. To provide the benefits of feature parity and enhanced security, with minimal impact on performance.
 
-    The VM utilized by Docker Desktop for Linux uses [`VirtioFS`](https://virtio-fs.gitlab.io), a shared file system that allows virtual machines to access a directory tree located on the host. Our internal benchmarking shows that with the right resource allocation to the VM, near native file system performance can be achieved with VirtioFS.
+   The VM utilized by Docker Desktop for Linux uses [`VirtioFS`](https://virtio-fs.gitlab.io), a shared file system that allows virtual machines to access a directory tree located on the host. Docker's internal benchmarking shows that with the right resource allocation to the VM, near native file system performance can be achieved with VirtioFS.
 
-    As such, we have adjusted the default memory available to the VM in Docker Desktop for Linux. You can tweak this setting to your specific needs by using the **Memory** slider within the **Settings** > **Resources** tab of Docker Desktop.
+   As such, the default memory available to the VM in Docker Desktop for Linux is adjusted. You can tweak this setting to your specific needs by using the **Memory** slider within the **Settings** > **Resources** tab of Docker Desktop.
 
 ### How do I enable file sharing?
 
 Docker Desktop for Linux uses [VirtioFS](https://virtio-fs.gitlab.io/) as the
 default (and currently only) mechanism to enable file sharing between the host
-and Docker Desktop VM. 
+and Docker Desktop VM.
 
 {{< accordion title="Additional information for Docker Desktop version 4.34 and earlier" >}}
 
@@ -59,7 +59,7 @@ mappings for IDs greater than 0 in the containers.
 
 | ID in container | ID on host                                                                       |
 | --------------- | -------------------------------------------------------------------------------- |
-| 0 (root)        | ID of the user running Docker Desktop (e.g. 1000)                                            |
+| 0 (root)        | ID of the user running Docker Desktop (e.g. 1000)                                |
 | 1               | 0 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100000) |
 | 2               | 1 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100001) |
 | 3               | 2 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100002) |
@@ -95,6 +95,34 @@ ACL (see `setfacl(1)`) for folders shared with the Docker Desktop VM.
 
 {{< /accordion >}}
 
+### How do I use Docker SDKs with Docker Desktop for Linux?
+
+Docker Desktop for Linux uses a per-user socket located at `~/.docker/desktop/docker.sock` instead of the system-wide `/var/run/docker.sock`. The Docker CLI handles this automatically through the `desktop-linux` context, but Docker SDKs and other tools that connect directly to the Docker daemon also need the `DOCKER_HOST` environment variable set.
+
+Without setting `DOCKER_HOST`, SDKs attempt to connect to `/var/run/docker.sock` and fail with an error like:
+
+```text
+Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
+```
+
+To fix this, set the `DOCKER_HOST` environment variable before running your SDK-based application:
+
+```console
+export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock
+```
+
+Or dynamically retrieve it from the `desktop-linux` context:
+
+```console
+export DOCKER_HOST=$(docker context inspect desktop-linux --format '{{ .Endpoints.docker.Host }}')
+```
+
+To make this permanent, add the export command to your shell profile (`~/.bashrc`, `~/.zshrc`, or similar):
+
+```console
+echo 'export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock' >> ~/.bashrc
+```
+
 ### Where does Docker Desktop store Linux containers?
 
 Docker Desktop stores Linux containers and images in a single, large "disk image" file in the Linux filesystem. This is different from Docker on Linux, which usually stores containers and images in the `/var/lib/docker` directory on the host's filesystem.
@@ -117,7 +145,7 @@ If the disk image file is too large, you can:
 
 To move the disk image file to a different location:
 
-1. Select **Settings** then  **Advanced** from the **Resources** tab.
+1. Select **Settings** then **Advanced** from the **Resources** tab.
 
 2. In the **Disk image location** section, select **Browse** and choose a new location for the disk image.
 
diff --git a/content/reference/api/engine/sdk/_index.md b/content/reference/api/engine/sdk/_index.md
@@ -44,6 +44,17 @@ For more information, see [Go client reference](https://pkg.go.dev/github.com/mo
 
 For more information, see [Docker Engine Python SDK reference](https://docker-py.readthedocs.io/).
 
+> [!NOTE]
+> Docker Desktop for Linux users
+>
+> Docker Desktop for Linux uses a per-user socket instead of the system-wide `/var/run/docker.sock`. To use Docker SDKs with Docker Desktop for Linux, set the `DOCKER_HOST` environment variable:
+>
+> ```bash
+> export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock
+> ```
+>
+> For more details, see [the Linux FAQs](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-use-docker-sdks-with-docker-desktop-for-linux).
+
 ## View the API reference
 
 You can
