Exploring and Optimizing Synchronized File Shares: Usage, `.syncignore` Files, and Known Issues

When the status indicator displays **Watching for filesystem changes**, your files are available to the VM through all the standard bind mount mechanisms, whether that's `-v` in the command line or specified in your `compose.yml` file. > [!NOTE] > > When you create a new service, setting the [bind mount option consistency](/reference/cli/docker/service/create.md#options-for-bind-mounts) to `:consistent` bypasses Synchronized file shares. > [!TIP] > > Docker Compose can automatically create file shares for bind mounts. > Ensure you're signed in to Docker with a paid subscription and have enabled both **Access experimental features** and **Manage Synchronized file shares with Compose** in Docker Desktop's settings. ## Explore your file share instance The **Synchronized file shares** section displays all your file share instances and provides useful information about each instance including: - The origin of the file share content - A status update - How much space each file share is using - The number of filesystem entry counts - The number of symbolic links - Which container(s) is using the file share instance Selecting a file share instance expands the dropdown and exposes this information. ## Use `.syncignore` You can use a `.syncignore` file at the root of each file share, to exclude local files from your file share instance. It supports the same syntax as `.dockerignore` files and excludes, and/or re-includes, paths from synchronization. `.syncignore` files are ignored at any location other than the root of the file share. Some example of things you might want to add to your `.syncignore` file are: - Large dependency directories, for example `node_modules` and `composer` directories (unless you rely on accessing them via a bind mount) - `.git` directories (again, unless you need them) In general, use your `.syncignore` file to exclude items that aren't critical to your workflow, especially those that would be slow to sync or use significant storage. ## Known issues - Changes made to `.syncignore` don't lead to immediate deletions unless the file share is recreated. In other words, files that are newly ignored due to modifications in the `.syncignore` file remain in their current location, but are no longer updated during synchronization. - File share instances are currently limited to approximately 2 million files per share. For best performance, if you have a file share instance of this size, try to decompose it into multiple shares corresponding to individual bind mount locations. - Case conflicts, due to Linux being case-sensitive and macOS/Windows only being case-preserving, display as **File exists** problems in the GUI. These can be ignored. However, if they persist, you can report the issue. - Synchronized file shares proactively reports temporary issues, which can result in occasional **Conflict** and **Problem** indicators appearing in the GUI during synchronization. These can be ignored. However, if they persist, you can report the issue. - If you switch from WSL2 to Hyper-V on Windows, Docker Desktop needs to be fully restarted. - POSIX-style Windows paths are not supported. Avoid setting the [`COMPOSE_CONVERT_WINDOWS_PATHS`](/manuals/compose/how-tos/environment-variables/envvars.md#compose_convert_windows_paths) environment variable in Docker Compose. - If you don't have the correct permissions to create symbolic links and your container attempts to create symbolic links in your file share instance, an **unable to create symbolic link** error message displays. For Windows users, see Microsoft's [Create symbolic links documentation](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-10/security/threat-protection/security-policy-settings/create-symbolic-links) for best practices and location of the **Create symbolic links** security policy setting. For Mac and Linux users, check that you have write permissions on the folder.

Once a file share instance is active and displays 'Watching for filesystem changes', files are accessible via standard bind mount mechanisms. Docker Compose can automate file share creation for bind mounts, but requires a paid Docker subscription and enabling specific experimental features. The Synchronized file shares section displays information about origin, status, usage, file counts, and container usage. Users can employ a `.syncignore` file (similar to `.dockerignore`) at the root of each file share to exclude specific files or directories from synchronization. Known issues include: `.syncignore` changes require file share recreation for deletions, file share limit of ~2 million files, case conflicts due to case sensitivity differences between OS, temporary synchronization conflicts, requirement of a full restart when switching between WSL2 and Hyper-V, lack of support for POSIX-style Windows paths, and potential permission errors when creating symbolic links.