Fixing 'mounts denied' and file sharing on Docker Desktop (macOS/Windows)

What this guide covers

You’ll learn how to diagnose and fix mounts denied and file sharing errors on Docker Desktop for macOS and Windows. We focus on path correctness, Docker Desktop settings, WSL2 specifics, and reliable volume mounts for docker run and docker compose.

Common symptoms:

• Error contains: "mounts denied", "file sharing is turned off", "drive is not shared", or permission denied when mounting host paths.
• Container sees an empty directory where a host folder was expected.

Minimal working example (MWE)

Use this to verify your environment before debugging your app.

Dockerfile:

FROM alpine:3.20
WORKDIR /app
CMD ["sh", "-c", "echo Mounted files:; ls -la /app"]

docker-compose.yml:

services:
  app:
    build: .
    volumes:
      - ./hostdata:/app

Create a test file and run:

# macOS/Linux shell
mkdir -p hostdata && echo "hello" > hostdata/hello.txt
docker compose up --build

On Windows PowerShell (non-WSL shell):

mkdir hostdata | Out-Null; 'hello' | Out-File -Encoding utf8 hostdata/hello.txt
docker compose up --build

Expected: the container prints a listing containing hello.txt.

If you get mounts denied, follow the steps below.

Quickstart: the fastest checks

1. Confirm the host path exists and is readable by you.

• macOS: ls -ld ./hostdata
• Windows: dir .\hostdata

1. Use correct path syntax in your command or compose file.

• macOS: -v "$PWD/hostdata:/app"
• Windows (PowerShell, non-WSL): -v "${PWD}\hostdata:/app" is not valid. Convert to a Docker path like //c/Users/you/project/hostdata:/app.

1. Ensure Docker Desktop can access the folder.

• In Docker Desktop Settings, verify your drive/folder is shared/allowed for file sharing (see OS-specific sections below).

1. Retry the MWE with docker run:

# macOS shell
docker run --rm -v "$PWD/hostdata:/app" alpine:3.20 ls -la /app

# Windows PowerShell (non-WSL)
docker run --rm -v //c/Users/you/project/hostdata:/app alpine:3.20 ls -la /app

macOS: common fixes

1. Path must be within shared roots.

• Default shared roots typically include /Users, /Volumes, /private, /tmp.
• If your path is outside these, move the project under ~/ (e.g., ~/Projects/app) or add the folder in Docker Desktop > Settings > Resources > File sharing.

1. Resolve symlinks and macOS private paths.

• Some GUI apps present paths under /private/var/...; Docker may expect the real path under /var or /Users.
• Resolve the real path before mounting: realpath ./hostdata

1. Permissions and quarantine.

• Ensure you have read permissions: chmod -R u+rwX ./hostdata
• If corporate security tools sandbox folders (e.g., Desktop sync), relocate the project to ~/Projects.

1. Compose path resolution.

• Compose resolves relative host paths relative to the compose file location. Keep the volume as - ./hostdata:/app and run docker compose from that directory.

1. Try read-only first to validate access without locks:

docker run --rm -v "$PWD/hostdata:/app:ro" alpine:3.20 ls -la /app

Windows: WSL2 vs non-WSL backends

First, check your backend: Docker Desktop > Settings > General > Use the WSL 2 based engine.

• WSL2 backend (recommended):

  • Best performance when your project lives in the Linux filesystem (e.g., \wsl$\Ubuntu\home\you\project). Accessing Windows files (C:...) from Linux containers is slower and can hit permission issues.
  • Use a WSL shell (Ubuntu) and run:

    mkdir -p ~/project/hostdata && echo hello > ~/project/hostdata/hello.txt
    cd ~/project
    docker run --rm -v "$PWD/hostdata:/app" alpine:3.20 ls -la /app
    

  • If you must mount Windows files, prefer the //wsl$/ mount when inside WSL, or use /mnt/c/... with awareness of slower I/O.

• Non-WSL backend (Hyper-V):

  • Ensure the drive is shared in Docker Desktop > Settings > Resources > File sharing (e.g., C: enabled). You may be prompted for Windows credentials.
  • Use Docker path format for volumes: //c/Users/you/project/hostdata:/app
  • If domain credentials change, re-share the drive: uncheck C:, Apply & Restart, re-enable C:.

Reliable path patterns by shell

• macOS or WSL shell:

  • docker run -v "$PWD/hostdata:/app" ...
  • docker run -v "$(pwd)/hostdata:/app" ...

• Windows PowerShell (non-WSL):

  • Convert to Docker-style path: //c/Users/you/project/hostdata:/app
  • Avoid -v "${PWD}\hostdata:/app" (backslashes) for Linux containers.

• docker-compose.yml (portable):

  • Use relative: - ./hostdata:/app and run compose from the file’s directory.

Step-by-step troubleshooting

1. Verify the host path exists and is not empty.
2. Replace the path with a simple, ASCII-only path (no spaces or special characters) to rule out encoding issues.
3. Test with read-only mount to isolate file-lock conflicts.
4. On macOS, confirm the path is under /Users (or add it to File sharing).
5. On Windows:
   • WSL2: move the project into the WSL filesystem and run from a WSL shell.
   • Hyper-V: ensure the drive is shared; re-enter credentials if prompted.
6. Remove symlinks in the host path or mount the resolved path (realpath on macOS/WSL).
7. In compose, ensure you run docker compose from the same directory as docker-compose.yml.
8. Try a fresh directory to rule out ACL/permission anomalies.
9. Restart Docker Desktop after changing file sharing settings.

Pitfalls and edge cases

• Trailing slashes: -v ./dir:/app differs from -v ./dir/:/app in some workflows; prefer consistent usage without trailing slash.
• Mounting parent directories: sharing your whole home or root can be blocked by policy; mount only what you need.
• Corporate security: endpoint protection may deny SMB/IPC for shared drives; request policy exceptions or use WSL2 filesystem.
• Hidden macOS paths: /private/var/... vs /var/...; use the canonical path.
• Large file watches: tools like webpack or nodemon can overload file sync; consider polling or reduced watchers.

Performance notes

• macOS: prefer VirtioFS/gRPC FUSE file sharing over legacy osxfs if available. Keep dependency caches (node_modules, vendor) inside the container or use bind mounts selectively to reduce overhead.
• Windows WSL2: store projects in the Linux filesystem for fast I/O. Accessing C:\ from WSL is slower. Use docker volumes for large, write-heavy paths (databases, caches).
• General: ignore files you don’t need with .dockerignore; avoid mounting build artifacts back into the container if not required.

Tiny FAQ

• The container can’t see my files, but no error appears.

  • Check that the host path exists and that compose ran from the correct directory.

• I see "drive is not shared" on Windows.

  • Enable sharing for the drive in Docker Desktop settings or use WSL2 with projects in the Linux filesystem.

• How do I test a mount from inside the container?

  • docker run --rm -it -v "$PWD/hostdata:/app" alpine:3.20 sh and run ls -la /app.

• Can I mount read-only for safety?

  • Yes: add :ro, e.g., -v "$PWD/hostdata:/app:ro".

• Compose still fails, but docker run works.

  • Compose resolves paths differently. Ensure you run from the compose file’s directory or use absolute paths.

Summary

• Use correct path syntax per OS/shell.
• Ensure Docker Desktop is allowed to access the folder/drive.
• Prefer WSL2 with projects in the Linux filesystem on Windows.
• Resolve symlinks, avoid special characters, and restart Docker Desktop after changes.