How to Exclude Specific Folders from iCloud Drive Syncing on Mac

When you enable Desktop & Documents folder synchronization in macOS, iCloud Drive seamlessly mirrors your files across all your Apple devices and preserves an off-site cloud backup. However, software development projects, virtual machines, local media caches, and large rendering scratch directories often reside inside your Documents folder. If left unrestricted, directories such as node_modules, Python virtual environments, and temporary build caches continuously trigger upload cycles, saturating your internet bandwidth and depleting your available iCloud storage tier. Mac users can prevent specific folders from uploading to Apple’s cloud servers without moving them out of their working directory tree.

Method 1: The Official Native .nosync Extension

Apple built an undocumented, natively recognised exclusion tag directly into the macOS file coordination and iCloud syncing daemon (bird). Any file or folder whose name ends with the extension .nosync is automatically flagged by macOS as a local-only resource and ignored by iCloud synchronization:

1. Launch Finder on your Mac and navigate to the directory located within your Documents or Desktop space that you wish to exclude.
2. Click on the folder name once or press Return to rename the directory.
3. Append .nosync to the very end of the folder name. For instance, rename a directory named ProjectAssets to:

   ProjectAssets.nosync

4. Press Return to confirm the modification. If macOS displays a confirmation prompt asking if you are sure you want to add an extension to a folder, click Add.

Within seconds, any active iCloud upload progress indicator beside that folder will disappear, and macOS will mark the entire tree as permanently excluded from cloud synchronization.

Creating Clean Symlinks to Preserve Script Paths

If you have existing codebases, build scripts, or terminal shortcuts that rely on the original folder path without the .nosync suffix, appending an extension directly can break automated dependencies. You can resolve this issue by pairing the .nosync folder with a symbolic link:

1. Open the Terminal app from Applications > Utilities.
2. Navigate to the parent folder containing your project:

   cd ~/Documents/Development

3. Rename the physical folder to include the exclusion extension:

   mv BuildCache BuildCache.nosync

4. Create a symbolic link that points from the original folder name to the excluded folder:

   ln -s BuildCache.nosync BuildCache

Your local build scripts and terminal commands will continue accessing BuildCache normally through the symlink, while the iCloud synchronization daemon detects the physical BuildCache.nosync target and bypasses it completely.

Method 2: Moving Large Directories to User Home Root

Another reliable architectural approach to avoid unwanted cloud uploads is relocating non-document assets outside the designated iCloud scope entirely:

• The macOS iCloud Desktop & Documents feature only monitors the ~/Desktop and ~/Documents directories.
• Folders placed directly under your user root directory (~/)—such as ~/Developer, ~/Projects, or ~/Scratch—are completely immune to automatic iCloud synchronization.
• To create a permanent local development folder, open Terminal and execute:

  mkdir ~/Developer

• Move your repositories, Docker volumes, and dependency packages into this directory to ensure local-only processing without consuming cloud storage.

Frequently Asked Questions

Does adding .nosync delete the files already stored in iCloud?

When you append .nosync to an existing folder that has already completed uploading, macOS will retain the local folder on your Mac’s internal drive while pruning the remote copy from iCloud Drive servers during the next synchronization handshake.

Can I apply .nosync to individual files as well as folders?

Yes. Appending .nosync to individual file names (e.g. archive.zip.nosync) prevents the designated file from uploading while keeping the rest of the parent folder synchronized.

What happens if I remove the .nosync extension later?

Removing .nosync restores the folder to standard operating status. The macOS bird daemon detects the name change and immediately begins queuing the contents for cloud backup and multi-device replication.