This error occurs on macOS when Docker Desktop cannot access a directory you're trying to mount. You need to add the path to Docker's file sharing settings in Preferences before bind mounting it into a container.
Docker Desktop on macOS runs containers inside a lightweight Linux virtual machine (VM). For security and performance reasons, Docker does not automatically grant containers access to your entire filesystem. Only directories that have been explicitly shared with Docker can be mounted into containers. When you see "The path /Users/username/project is not shared from OS X and is not known to Docker," Docker is telling you that the specific directory you're trying to mount hasn't been configured as a shared folder in Docker Desktop's settings. By default, Docker Desktop for Mac shares these directories: - `/Users` (your home directory and all user directories) - `/Volumes` (mounted external drives) - `/private` (system directories, including `/tmp` via symlink) - `/tmp` (temporary files) Paths outside these defaults, or paths with symbolic links that resolve outside them, require manual configuration in Docker Desktop preferences.
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/varDocker 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/varIf 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" myimage3. 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 myimageThis 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.json3. 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.backupIf 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 settingsOption 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.
Understanding Docker Desktop's file sharing architecture:
Docker Desktop runs a Linux VM using Apple's Virtualization framework (on Apple silicon) or HyperKit (on Intel Macs). The file sharing system creates a bridge between your macOS filesystem and the Linux VM where containers run.
Performance implications:
File sharing has overhead because every file operation must cross the VM boundary:
- VirtioFS (default): Best performance, uses Apple's native virtualization
- gRPC FUSE: Good balance of performance and compatibility
- osxfs: Original implementation, slower but most compatible
For performance-critical workloads with many files (like node_modules), consider using named volumes instead of bind mounts.
Troubleshooting checklist:
1. Is the path within a shared directory? Check with realpath
2. Does the path contain symlinks? Resolve them
3. Is Docker Desktop running and healthy? Check docker info
4. Was File Sharing recently modified? Restart Docker
5. Did you recently update Docker Desktop? Check release notes
macOS Sequoia (15.x) and later:
Some users report file sharing issues on macOS Sequoia. Apple's enhanced security may require additional permissions. Check System Preferences > Privacy & Security > Files and Folders to ensure Docker has access.
Docker contexts and remote hosts:
This error only affects Docker Desktop on macOS. If you're using a remote Docker host (via docker context or DOCKER_HOST), bind mounts reference the remote host's filesystem, not your local Mac's filesystem.
Related errors:
- "Mounts denied: path is not shared from the host" (generic version)
- "Error response from daemon: invalid mount config" (different root cause)
- "Cannot create container: no such file or directory" (path doesn't exist)
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub