Fix 'path is not shared from the host' on Docker Desktop

Overview

“The path … is not shared from the host and is not known to Docker” appears when a bind mount points to a host path Docker Desktop cannot access. This is common on macOS and Windows when the directory or drive is not added to Docker Desktop’s File Sharing list, or when path syntax is wrong for the shell.

This guide shows quick fixes and deeper steps for Docker Desktop (macOS/Windows), plus WSL2, Compose, and shell-specific nuances.

Symptoms

• docker run or docker compose up fails with the error above.
• Paths outside default shares (e.g., /opt on macOS, D:\ on Windows) are common triggers.
• Git Bash/Cygwin paths like /c/Users/... behave inconsistently unless configured.

Quickstart: the 90-second fix

1. Identify the host path you’re mounting (left side of -v or source in Compose).
2. Open Docker Desktop → Settings → Resources → File Sharing.
3. Add the directory (macOS) or drive letter/directory (Windows) you want to mount.
4. Apply & restart Docker Desktop.
5. Re-run your container with correct path syntax for your shell (examples below).

Minimal working example (MWE)

The examples mount a host directory into an Alpine container and list its contents.

macOS/Linux (bash or zsh):

# Example that may fail if /opt is not shared on macOS
sudo mkdir -p /opt/demo
sudo chmod 755 /opt/demo

docker run --rm -v /opt/demo:/data alpine ls -la /data
# If you get the error, add /opt (or /opt/demo) in Docker Desktop File Sharing,
# Apply & Restart, then run the command again.

Windows PowerShell:

New-Item -ItemType Directory -Force -Path C:\demo | Out-Null

docker run --rm -v C:\demo:/data alpine ls -la /data
# If you get the error, share C:\ (or C:\demo) in Docker Desktop File Sharing,
# then retry.

Windows Git Bash (MSYS2 path conversion note):

# Either use Windows-style path
docker run --rm -v C:\\demo:/data alpine ls -la /data
# Or disable MSYS path conversion for this command
MSYS_NO_PATHCONV=1 docker run --rm -v /c/demo:/data alpine ls -la /data

docker-compose (portable long syntax):

version: "3.9"
services:
  demo:
    image: alpine
    command: ["sh", "-lc", "ls -la /data"]
    volumes:
      - type: bind
        source: ./demo
        target: /data

Note: Create a ./demo directory next to your compose file. On macOS/Windows, ensure the parent folder is shared.

Step-by-step diagnosis and fixes

1. Confirm the exact host path

   • docker run: the left side of -v host:container.
   • Compose: volumes[].source or the left side of short syntax.

2. Check Docker Desktop sharing

   • macOS: Add the directory (e.g., /opt/demo) in Settings → Resources → File Sharing.
   • Windows: Add the drive (e.g., D:) or directory (e.g., C:\projects) in File Sharing.
   • Apply & restart Docker Desktop.

3. Use correct path syntax for your shell

   • PowerShell/CMD: C:\path\to\dir:/mountpoint
   • Git Bash/Cygwin: use Windows style (C:\path) or set MSYS_NO_PATHCONV=1 and use /c/path.
   • WSL2: use Linux paths (/home/user/project or /mnt/c/Users/...). If running docker from WSL, prefer paths within your distro for performance.

4. Avoid special/unsupported sources

   • UNC paths (\server\share) often fail; map them to a drive letter and share that drive, or use a CIFS mount inside WSL/Linux and bind from there.
   • External disks may need explicit sharing.

5. Re-run and verify

   • If the error persists, test with a simpler parent folder known to be shared (e.g., your home directory) to isolate the issue.

Shell and path syntax quick reference

• PowerShell: -v C:\Users\you\proj:/app
• CMD: -v C:\Users\you\proj:/app
• Git Bash: -v C:\Users\you\proj:/app or MSYS_NO_PATHCONV=1 -v /c/Users/you/proj:/app
• WSL2 bash: -v /home/you/proj:/app or -v /mnt/c/Users/you/proj:/app

Tip: Spaces in Windows paths require quotes; e.g., -v "C:\My Projects\app":/app

macOS specifics

• Default shared paths usually include /Users but not necessarily /opt or external volumes.
• If you use /private/var or /Volumes, add them explicitly.
• Symlinks: the symlink target must be within a shared path. If you mount a symlink whose target is outside shared paths, you may still hit the error.

Windows specifics

• Drives must be shared and may prompt for credentials. If you denied the prompt earlier, re-enable sharing via Settings → Resources → File Sharing.
• Git Bash path conversion can corrupt mount arguments. Use Windows-style paths or set MSYS_NO_PATHCONV=1 for docker run and MSYS2_ARG_CONV_EXCL for compose:

export MSYS_NO_PATHCONV=1
export MSYS2_ARG_CONV_EXCL='*'

• If using CMD/PowerShell, prefer absolute paths; relative paths resolve to the current working directory.

WSL2 backend notes

• If you run docker from inside WSL2, volumes using Linux paths within the distro (e.g., /home/you/app) are fastest and do not require Desktop File Sharing.
• Accessing Windows files via /mnt/c works, but is slower; avoid for heavy I/O.
• UNC shares (\server\share) are not directly bind-mountable; map to a drive or mount via CIFS in WSL, then bind that mounted path.

Compose: short vs long syntax

• Short syntax (./host:/container) works but can be ambiguous on Windows shells.
• Prefer long syntax for clarity and cross-platform reliability:

volumes:
  - type: bind
    source: ./host
    target: /container

• On Windows, avoid backslashes in YAML; use forward slashes for relative paths (./host), or quote absolute Windows paths if needed:

volumes:
  - type: bind
    source: "C:/Users/you/proj"
    target: /app

Common pitfalls

• Mounting a path you don’t have filesystem permissions to read (host-side). Fix with chmod/chown (macOS) or adjust NTFS ACLs (Windows).
• Using a symlink to a directory outside shared paths.
• Mixing shells: running compose from Git Bash after testing docker run in PowerShell with different path formats.
• Network shares without mapping to a drive or without CIFS mount inside WSL/Linux.

Performance notes

• Bind mounts on macOS/Windows are slower than native Linux due to virtualization.
• Tips:
  • Prefer named volumes for large datasets or database storage.
  • On WSL2, keep code in the Linux filesystem (/home) for best performance.
  • On macOS, enable the faster file sharing backend (e.g., gRPC FUSE/VirtioFS in Docker Desktop) if available.
  • Limit the number of bind-mounted files when possible.

Tiny FAQ

• Why does it work in my home directory but not in /opt?

  • Your home is shared by default; /opt isn’t. Add /opt in File Sharing.

• Do I need to share paths on Linux?

  • No. This error is specific to Docker Desktop (macOS/Windows). On Linux you’d more likely see a permissions error.

• Can I mount a UNC path like \server\share?

  • Not directly. Map it to a drive and share that drive, or mount via CIFS inside WSL/Linux and bind from that mountpoint.

• Compose still fails from Git Bash. Why?

  • MSYS path conversion may rewrite arguments. Use long syntax and export MSYS2_ARG_CONV_EXCL='*', or run compose from PowerShell/WSL.

Summary

• Share the host directory/drive in Docker Desktop.
• Use correct path syntax for your shell (PowerShell, Git Bash, or WSL2).
• Avoid UNC paths; map or mount them properly.
• Prefer long syntax in Compose and keep heavy I/O on native filesystems.