Skip to content

Desktop: Networking how-tos #23708

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 3 commits into from
Nov 17, 2025
Merged

Desktop: Networking how-tos #23708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
42fd89a
Desktop: Networking how-tos
aevesdocker Nov 12, 2025
adfd078
edits
aevesdocker Nov 12, 2025
b0cf52e
Apply suggestions from code review
aevesdocker Nov 17, 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
270 changes: 73 additions & 197 deletions content/manuals/desktop/features/networking/networking-how-tos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,62 +14,97 @@
- /desktop/networking/
---

Docker Desktop includes built-in networking capabilities to help you connect containers with services on your host, across containers, or through proxies and VPNs.
This page explains how to configure and use networking features, connect containers to host services, work behind proxies or VPNs, and troubleshoot common issues.

## Networking features for all platforms
For details on how Docker Desktop routes network traffic and file I/O between containers, the VM, and the host, see [Network overview](/manuals/desktop/features/networking/index.md#overview).

### VPN Passthrough
## Core networking how-tos

### Connect a container to a service on the host

The host has a changing IP address, or none if you have no network access. To connect to services running on your host, use the special DNS name:

| Name | Description |
| ------------------------- | ------------------------------------------------ |
| `host.docker.internal` | Resolves to the internal IP address of your host |
| `gateway.docker.internal` | Resolves to the gateway IP of the Docker VM |

Docker Desktop networking can work when attached to a VPN. To do this,
Docker Desktop intercepts traffic from the containers and injects it into
the host as if it originated from the Docker application.

### Port mapping
#### Example

When you run a container with the `-p` argument, for example:
Run a simple HTTP server on port `8000`:

```console
$ docker run -p 80:80 -d nginx
$ python -m http.server 8000
```

Docker Desktop makes whatever is running on port `80` in the container, in
this case, `nginx`, available on port `80` of `localhost`. In this example, the
host and container ports are the same.
Then run a container, install `curl`, and try to connect to the host using the following commands:

To avoid conflicts with services already using port `80` on the host:
```console
$ docker run --rm -it alpine sh
# apk add curl
# curl http://host.docker.internal:8000
# exit
```

### Connect to a container from the host

To access containerized services from your host or local network, publish ports with the `-p` or `--publish` flag. For example:

```console
$ docker run -p 8000:80 -d nginx
$ docker run -d -p 80:80 --name webserver nginx
```

Now connections to `localhost:8000` are sent to port `80` in the container.
Docker Desktop makes whatever is running on port `80` in the container, in
this case, `nginx`, available on port `80` of `localhost`.

> [!TIP]
>
> The syntax for `-p` is `HOST_PORT:CLIENT_PORT`.

### HTTP/HTTPS Proxy support
To publish all ports, use the `-P` flag. For example, the following command
starts a container (in detached mode) and the `-P` flag publishes all exposed ports of the
container to random ports on the host.

```console
$ docker run -d -P --name webserver nginx
```

Alternatively, you can also use [host networking](/manuals/engine/network/drivers/host.md#docker-desktop)
to give the container direct access to the network stack of the host.

See the [run command](/reference/cli/docker/container/run.md) for more details on
publish options used with `docker run`.

All inbound connections pass through the Docker Desktop backend process (`com.docker.backend` (Mac), `com.docker.backend` (Windows), or `qemu` (Linux), which handles port forwarding into the VM.
For more details, see [How exposed ports work](/manuals/desktop/features/networking/index.md#how-exposed-ports-work)

See [Proxies](/manuals/desktop/settings-and-maintenance/settings.md#proxies)
### Working with VPNs

### SOCKS5 proxy support
Docker Desktop networking can work when attached to a VPN.

{{< summary-bar feature_name="SOCKS5 proxy support" >}}
To do this, Docker Desktop intercepts traffic from the containers and injects it into
the host as if it originated from the Docker application.

SOCKS (Socket Secure) is a protocol that facilitates the routing of network packets between a client and a server through a proxy server. It provides a way to enhance privacy, security, and network performance for users and applications.
For details about how this traffic appears to host firewalls and endpoint detection systems, see [Firewalls and endpoint visibility](/manuals/desktop/features/networking/index.md#firewalls-and-endpoint-visibility.md).

You can enable SOCKS proxy support to allow outgoing requests, such as pulling images, and access Linux container backend IPs from the host.
### Working with proxies

To enable and set up SOCKS proxy support:
Docker Desktop can use your system proxy or a manual configuration.
To configure proxies:

1. Navigate to the **Resources** tab in **Settings**.
2. From the dropdown menu select **Proxies**.
3. Switch on the **Manual proxy configuration** toggle.
4. In the **Secure Web Server HTTPS** box, paste your `socks5://host:port` URL.
3. Switch on the **Manual proxy configuration** toggle.
4. Enter your HTTP, HTTPS or SOCKS5 proxy URLS.

## Networking mode and DNS behaviour for Mac and Windows
For more details on proxies and proxy configurations, see the [Proxy settings documentation](/manuals/desktop/settings-and-maintenance/settings.md#proxies).

With Docker Desktop version 4.42 and later, you can customize how Docker handles container networking and DNS resolution to better support a range of environments — from IPv4-only to dual-stack and IPv6-only systems. These settings help prevent timeouts and connectivity issues caused by incompatible or misconfigured host networks.
## Network how-tos for Mac and Windows

With Docker Desktop version 4.42 and later, you can control how Docker handles container networking and DNS resolution to better support a range of environments — from IPv4-only to dual-stack and IPv6-only systems. These settings help prevent timeouts and connectivity issues caused by incompatible or misconfigured host networks.

Check failure on line 105 in content/manuals/desktop/features/networking/networking-how-tos.md

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'misconfigured'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'misconfigured'?", "location": {"path": "content/manuals/desktop/features/networking/networking-how-tos.md", "range": {"start": {"line": 105, "column": 303}}}, "severity": "ERROR"}

You can set the following settings on the **Network** tab in the Docker Desktop Dashboard settings, or if you're an admin, with Settings Management via the [`admin-settings.json` file](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#networking), or the [Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md)

> [!NOTE]
>
Expand All @@ -79,123 +114,28 @@

Choose the default IP protocol used when Docker creates new networks. This allows you to align Docker with your host’s network capabilities or organizational requirements, such as enforcing IPv6-only access.

The options available are:

- **Dual IPv4/IPv6** (Default): Supports both IPv4 and IPv6. Most flexible and ideal for environments with dual-stack networking.
- **IPv4 only**: Only IPv4 addresses are used. Use this if your host or network does not support IPv6.
- **IPv6 only**: Only IPv6 addresses are used. Best for environments transitioning to or enforcing IPv6-only connectivity.

> [!NOTE]
>
> This setting can be overridden on a per-network basis using CLI flags or Compose file options.
| Mode | Description |
| ---------------------------- | ------------------------------------------- |
| **Dual IPv4/IPv6 (default)** | Supports both IPv4 and IPv6. Most flexible. |
| **IPv4 only** | Uses only IPv4 addressing. |
| **IPv6 only** | Uses only IPv6 addressing. |

### DNS resolution behavior

Control how Docker filters DNS records returned to containers, improving reliability in environments where only IPv4 or IPv6 is supported. This setting is especially useful for preventing apps from trying to connect using IP families that aren't actually available, which can cause avoidable delays or failures.

Depending on your selected network mode, the options available are:

- **Auto (recommended)**: Docker detects your host's network stack and automatically filters out unsupported DNS record types (A for IPv4, AAAA for IPv6).
- **Filter IPv4 (A records)**: Prevents containers from resolving IPv4 addresses. Only available in dual-stack mode.
- **Filter IPv6 (AAAA records)**: Prevents containers from resolving IPv6 addresses. Only available in dual-stack mode.
- **No filtering**: Docker returns all DNS records (A and AAAA), regardless of host support.
| Option | Description |
| ------------------------------ | --------------------------------------------------------------------------- |
| **Auto (recommended)** | Automatically filters unsupported record types. (A for IPv4, AAAA for IPv6) |
| **Filter IPv4 (A records)** | Blocks IPv4 lookups. Only available in dual-stack mode. |
| **Filter IPv6 (AAAA records)** | Blocks IPv6 lookups. Only available in dual-stack mode. |
| **No filtering** | Returns both A and AAAA records. |

> [!IMPORTANT]
>
> Switching the default networking mode resets the DNS filter to Auto.

### Using Settings Management

If you're an administrator, you can use [Settings Management](/manuals/enterprise/security/hardened-desktop/settings-management/configure-json-file.md#networking) to enforce this Docker Desktop setting across your developer's machines. Choose from the following code snippets and at it to your `admin-settings.json` file,
or configure this setting using the [Admin Console](/manuals/enterprise/security/hardened-desktop/settings-management/configure-admin-console.md)

{{< tabs >}}
{{< tab name="Networking mode" >}}

Dual IPv4/IPv6:

```json
{
"defaultNetworkingMode": {
"locked": true
"value": "dual-stack"
}
}
```

IPv4 only:

```json
{
"defaultNetworkingMode": {
"locked": true
"value": "ipv4only"
}
}
```

IPv6 only:

```json
{
"defaultNetworkingMode": {
"locked": true
"value": "ipv6only"
}
}
```

{{< /tab >}}
{{< tab name="DNS resolution" >}}

Auto filter:

```json
{
"dnsInhibition": {
"locked": true
"value": "auto"
}
}
```

Filter IPv4:

```json
{
"dnsInhibition": {
"locked": true
"value": "ipv4"
}
}
```

Filter IPv6:

```json
{
"dnsInhibition": {
"locked": true
"value": "ipv6"
}
}
```

No filter:

```json
{
"dnsInhibition": {
"locked": true
"value": "none"
}
}
```

{{< /tab >}}
{{< /tabs >}}

## Networking features for Mac and Linux
## Network how-tos for Mac and Linux

### SSH agent forwarding

Expand Down Expand Up @@ -248,67 +188,3 @@

This is because the Docker `bridge` network is not reachable from the host.
However if you are a Windows user, per-container IP addressing is possible with Windows containers.

## Use cases and workarounds

### I want to 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.
Docker recommends you connect to the special DNS name `host.docker.internal`,
which resolves to the internal IP address used by the host.

You can also reach the gateway using `gateway.docker.internal`.

If you have installed Python on your machine, use the following instructions as an example to connect from a container to a service on the host:

1. Run the following command to start a simple HTTP server on port 8000.

`python -m http.server 8000`

If you have installed Python 2.x, run `python -m SimpleHTTPServer 8000`.

2. Now, run a container, install `curl`, and try to connect to the host using the following commands:

```console
$ docker run --rm -it alpine sh
# apk add curl
# curl http://host.docker.internal:8000
# exit
```

### I want to connect to a container from the host

Port forwarding works for `localhost`. `--publish`, `-p`, or `-P` all work.
Ports exposed from Linux are forwarded to the host.

Docker recommends you publish a port, or to connect from another
container. This is what you need to do even on Linux if the container is on an
overlay network, not a bridge network, as these are not routed.

For example, to run an `nginx` webserver:

```console
$ docker run -d -p 80:80 --name webserver nginx
```

To clarify the syntax, the following two commands both publish container's port `80` to host's port `8000`:

```console
$ docker run --publish 8000:80 --name webserver nginx

$ docker run -p 8000:80 --name webserver nginx
```

To publish all ports, use the `-P` flag. For example, the following command
starts a container (in detached mode) and the `-P` flag publishes all exposed ports of the
container to random ports on the host.

```console
$ docker run -d -P --name webserver nginx
```

Alternatively, you can also use [host networking](/manuals/engine/network/drivers/host.md#docker-desktop)
to give the container direct access to the network stack of the host.

See the [run command](/reference/cli/docker/container/run.md) for more details on
publish options used with `docker run`.
6 changes: 4 additions & 2 deletions content/manuals/desktop/settings-and-maintenance/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,16 +233,18 @@ containers. Alternatively, you can opt not to share it by selecting **Cancel**.

### Proxies

Docker Desktop supports the use of HTTP/HTTPS and [SOCKS5 proxies](/manuals/desktop/features/networking.md#socks5-proxy-support).
Docker Desktop supports the use of HTTP/HTTPS and SOCKS5 proxies (Requires a business subscription).

HTTP/HTTPS proxies can be used when:
HTTP/HTTPS and SOCKS5 proxies can be used when:

- Signing in to Docker
- Pulling or pushing images
- Fetching artifacts during image builds
- Containers interact with the external network
- Scanning images

For more details on how it works, see [Using Docker Desktop with a proxy](/manuals/desktop/features/networking/index.md#useing-docker-desktop-with-a-proxy).

If the host uses a HTTP/HTTPS proxy configuration (static or via Proxy Auto-Configuration (PAC)), Docker Desktop reads
this configuration
and automatically uses these settings for signing in to Docker, for pulling and pushing images, and for
Expand Down
2 changes: 1 addition & 1 deletion content/manuals/desktop/troubleshoot-and-support/faqs/general.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ The host has a changing IP address, or none if you have no network access.
It is recommend that you connect to the special DNS name `host.docker.internal`,
which resolves to the internal IP address used by the host.

For more information and examples, see [how to connect from a container to a service on the host](/manuals/desktop/features/networking.md#i-want-to-connect-from-a-container-to-a-service-on-the-host).
For more information and examples, see [how to connect from a container to a service on the host](/manuals/desktop/features/networking.md#connect-a-container-to-a-service-on-the-host).

### Can I pass through a USB device to a container?

Expand Down
2 changes: 1 addition & 1 deletion data/engine-cli/docker_container_run.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2262,7 +2262,7 @@ examples: |-
It's conventional to use `host.docker.internal` as the hostname referring to
`host-gateway`. Docker Desktop automatically resolves this hostname, see
[Explore networking features](/desktop/features/networking/networking-how-tos/#i-want-to-connect-from-a-container-to-a-service-on-the-host).
[Explore networking features](/desktop/features/networking/networking-how-tos/#connect-a-container-to-a-service-on-the-host).
The following example shows how the special `host-gateway` value works. The
example runs an HTTP server that serves a file from host to container over the
Expand Down
Loading