How to Fix "docker-compose error: path is not shared from OS X"

The "path is not shared from OS X" error occurs on macOS when Docker Desktop tries to bind-mount a host directory that has not been authorized under the Virtual Machine's File Sharing configuration. Because Docker on macOS runs inside a lightweight Linux hypervisor (VirtioFS, gRPC Fuse, or HyperKit), host paths must be explicitly exported into the VM before containers can mount them as volumes. Updating your Docker Desktop settings or correcting path references solves this immediately.

The Problem

When running docker-compose up or docker run -v with a host volume mount located outside standard directories (like /Users), the container engine aborts mounting and throws an error in your terminal:

ERROR: for web Container failed to start: error staging mount: path /var/www/app is not shared from OS X and cannot be known

Depending on your Docker Desktop version and backend storage driver (VirtioFS vs gRPC Fuse), you may see related variations of this error message:

docker-compose error: path is not shared from OS X

Error response from daemon: mount path /opt/data is not shared from the host OS X and cannot be mounted

Why It Happens

Docker Desktop on macOS operates through a virtualized environment. Host files are shared across the macOS host boundary into the hypervisor layer using specific mount definitions. Here are the primary root causes:

• Mount Outside Permitted Roots: By default, Docker Desktop only shares directories under /Users, /Volumes, /tmp, and /private. Custom paths like /var/www or /opt are blocked.
• Symlink Resolution: Your project path resides inside /Users, but includes a symlink pointing to an unshared system directory like /var or /private/var.
• Relative Path Expansion in Compose: A docker-compose.yml file uses relative paths (e.g., ./data:/var/lib/data) resolved from an unexpected working directory outside shared locations.

The Fix

To resolve this error, explicitly add your host directory path to the Virtual Machine File Sharing settings in Docker Desktop.

Step 1: Open Docker Desktop Preferences

Click the Docker icon in the macOS menu bar and select Settings (or Preferences on older versions).

Step 2: Navigate to File Sharing Settings

In the left sidebar, navigate to Resources and then select File Sharing (or Virtualization Options depending on whether you use VirtioFS, gRPC Fuse, or osxfs).

Step 3: Add your host path

Click the + (plus) button or edit the directory list. Type or select the directory path on your Mac that you want to share (e.g., /var/www or /opt/project).

Step 4: Apply and Restart

Click Apply & restart at the bottom right. Docker Desktop will restart the internal virtual machine with the updated volume exports.

Step 5: Verify working directory references in Docker Compose

Ensure your docker-compose.yml references paths correctly inside your shared home directory structure using standard relative syntax:

version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - .:/usr/share/nginx/html
      - ./config/nginx.conf:/etc/nginx/conf.d/default.conf

Run docker-compose up -d again to confirm the volume mounts mount cleanly into the container without OS X sharing exceptions.

Still Not Working?

If you are trying to mount system paths like /private/tmp or /var, macOS macOS symlink resolution can cause the path to expand differently than expected. For example, macOS aliases /var to /private/var.

Check the canonical path using realpath:

realpath /var/www/app

If realpath returns /private/var/www/app, add /private/var/www/app (or simply /private) to your Docker Desktop File Sharing list instead of /var/www/app.