How to fix Mounts denied: The path /Users/username/project is not shared from OS X and is not known to Docker in Docker

Find the full path that Docker is trying to mount. Check your docker command or docker-compose.yml:

# Check your docker run command for -v or --mount flags
docker run -v /path/to/mount:/container/path myimage

# Check docker-compose.yml volumes section
cat docker-compose.yml | grep -A 10 volumes:

On macOS, many paths are actually symlinks. Resolve them to see the actual path:

# Resolve symlinks to get the real path
realpath /var/folders/xx/yourpath

# Check if a path is a symlink
ls -la /var
# Output: lrwxr-xr-x  1 root  wheel  11 Jan  1  2020 /var -> private/var

Docker needs access to the resolved path, not just the symlink.

Navigate to Docker Desktop's file sharing configuration:

1. Click the Docker whale icon in your Mac's menu bar
2. Select Preferences... (or Settings...)
3. In the left sidebar, click Resources
4. Click File Sharing

You'll see a list of currently shared directories. By default, this includes /Users, /Volumes, /private, and /tmp.

Note: If you're using Docker Desktop 4.18 or later with VirtioFS (the default), file sharing works differently. VirtioFS provides access to most user directories automatically, but some edge cases still require manual configuration.

Add your directory (or a parent directory) to Docker's shared folders:

1. In File Sharing settings, click the + button
2. Navigate to and select the directory you need to mount
3. Click Open to add it
4. Click Apply & Restart

Tips:
- Share a parent directory (like /data or /projects) to avoid adding each subdirectory
- Avoid sharing your entire root filesystem (/) for security reasons
- If the directory doesn't appear in the list, try closing and reopening Preferences

Common paths that may need to be added:
- Custom project directories outside /Users
- /var/folders (temp files location)
- /opt or /usr/local for development tools

macOS uses symlinks extensively. Docker resolves symlinks before checking permissions, so you may need to share both the symlink path and its target.

Example: /var/folders issue

/var is symlinked to /private/var:

ls -la /var
# /var -> private/var

If your path involves /var/folders, Docker actually needs access to /private/var/folders.

Solutions:

1. Add the resolved path to File Sharing:
Add /private/var/folders instead of /var/folders

2. Use the resolved path in your Docker command:

# Instead of:
   docker run -v /var/folders/xx/path:/container myimage

   # Use:
   docker run -v /private/var/folders/xx/path:/container myimage

   # Or dynamically resolve it:
   docker run -v "$(realpath /var/folders/xx/path):/container" myimage

3. Common macOS symlinks to be aware of:
- /var -> /private/var
- /tmp -> /private/tmp
- /etc -> /private/etc

If adding custom paths to File Sharing doesn't work or isn't convenient, move your project to a directory that's already shared:

Default shared locations on macOS:
- /Users/yourusername/ (recommended for projects)
- /tmp (for temporary files)
- /Volumes/ (for external drives)

Example:

# Move project to home directory
mv /custom/location/myproject ~/Projects/myproject

# Update your working directory
cd ~/Projects/myproject

# Now Docker can mount it
docker run -v ~/Projects/myproject:/app myimage

This is often the simplest solution if you have flexibility in where your project lives.

Docker Desktop for Mac has evolved its file sharing implementation. If you experience persistent issues after updates, try switching the backend:

1. Open Docker Desktop Preferences
2. Go to General tab
3. Look for Choose file sharing implementation for your containers
4. Try switching between these options:
- VirtioFS (fastest, default on newer versions)
- gRPC FUSE (good compatibility)
- osxfs (Legacy) (slowest but most compatible)
5. Click Apply & Restart

Some users report that switching from VirtioFS to gRPC FUSE resolves file sharing issues that appeared after Docker Desktop updates.

Note: VirtioFS requires macOS 12.5+ and Apple silicon or newer Intel Macs. If it's causing issues, gRPC FUSE is a reliable fallback.

If the Docker Desktop UI doesn't let you add certain paths, you can edit the settings file directly:

1. Quit Docker Desktop completely

2. Open the settings file:

open ~/Library/Group\ Containers/group.com.docker/settings.json

3. Find or add the `filesharingDirectories` array:

{
     "filesharingDirectories": [
       "/Users",
       "/Volumes",
       "/private",
       "/tmp",
       "/var/folders",
       "/your/custom/path"
     ]
   }

4. Save the file and restart Docker Desktop

Warning: Edit carefully - invalid JSON will prevent Docker from starting. Back up the file first:

cp ~/Library/Group\ Containers/group.com.docker/settings.json ~/settings.json.backup

If file sharing is completely broken, reset Docker Desktop's configuration:

Option 1: Reset only settings

# Backup current settings
cp ~/Library/Group\ Containers/group.com.docker/settings.json ~/docker-settings-backup.json

# Remove the settings file
rm ~/Library/Group\ Containers/group.com.docker/settings.json

# Restart Docker Desktop - it will create fresh settings

Option 2: Full factory reset
1. Open Docker Desktop
2. Click Troubleshoot (bug icon) in the top right
3. Click Reset to factory defaults

Warning: Factory reset removes all containers, images, volumes, and settings. Only use as a last resort.

After resetting, you'll need to reconfigure your file sharing paths.