docs: add Local Network permission troubleshooting for Mac (#26279)

<!--Delete sections as needed -->

## Description

Adds a Mac troubleshooting topic for containers that can reach the
internet but not devices on the local network (LAN). The cause is Docker
Desktop not having the macOS **Local Network** permission: macOS then
blocks container traffic to devices on the local network, including the
router, while internet traffic still works. The fix is turning on Docker
in **System Settings** > **Privacy & Security** > **Local Network**,
which takes effect immediately, without restarting Docker Desktop.

Also adds a short **Local Network permission** section to the Mac
permission requirements page that links to the new topic, since that
page didn't mention it.

**Verified** on macOS 26.7 / Docker Desktop 4.92.0 by toggling Local
Network for Docker:
- Off: containers couldn't reach LAN peers or the default gateway (ping,
TCP, UDP DNS), while the internet and `docker pull` kept working.
- On: access came back immediately, on the same backend process, without
restarting Docker Desktop.
- **On a fresh install, macOS prompts for the Local Network permission,
so users who hit this have most likely denied that prompt at some
point.**

## Related issues or tickets

- https://github.com/docker/desktop-feedback/issues/636

## Reviews

- [ ] Technical review @mat007
- [ ] Editorial review
- [ ] Product review

---------

Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
This commit is contained in:
Salman RanaandAllie Sadler authored and GitHub committed 2026-10-20 15:40:39 +01:00
1 parent 5bd4f66c63
commit d533c61c19
2 files changed
+25

No files matched your search

@@ -51,6 +51,10 @@ It is your responsibility to ensure that localhost is resolved to `127.0.0.1` an
You can choose to enable privileged port mapping during installation (version 4.88.0 and earlier), or from the **Advanced** page in **Settings** post-installation. Docker Desktop requires authorization to confirm this choice.
## Local Network permission
For containers to reach devices on your local network, Docker Desktop needs the macOS **Local Network** permission. You can check it in **System Settings** > **Privacy & Security** > **Local Network**. See [Containers can't reach devices on my local network](/manuals/desktop/troubleshoot-and-support/troubleshoot/topics.md#containers-cant-reach-devices-on-my-local-network).
## Installing from the command line
Privileged configurations are applied during the installation with the `--user` flag on the [install command](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line). In this case, you are not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag:
@@ -229,6 +229,27 @@ To avoid this issue in the future:
- In managed environments, use PKG installations over DMG drag-and-drop
- Keep installer volumes mounted until installation is complete
### Containers can't reach devices on my local network
Containers can reach the internet, but not other devices on your local network
(LAN), such as a NAS, a printer, or another computer at a `192.168.x.x`
address. The device itself can reach them.
#### Cause
Docker Desktop doesn't have the Mac **Local Network** permission. Mac then
blocks container traffic to devices on your local network, including your
router, while traffic to the internet still works.
#### Solution
To give Docker Desktop the Local Network permission:
1. On your device, open **System Settings** > **Privacy & Security** > **Local Network**.
2. Turn on **Docker**.
The change applies immediately, without needing to restart Docker Desktop.
## Topics for Windows
### Docker Desktop fails to start when anti-virus software is installed