iCloud Drive wants to sync everything it can see. For normal documents, that is fine. For code projects, RAW photo folders, local databases, and private keys, it can be a mess. If you have searched for how to exclude folders from iCloud Drive on Mac, you already know the frustrating part: Apple gives you broad switches, not precise controls. These are the methods that actually work.
Why you would want to exclude folders from iCloud Drive
iCloud Drive is good at the ordinary stuff: documents, photos, PDFs, a few files you want everywhere. It gets awkward when a folder should stay local, changes constantly, or contains things you can recreate.
- Developer projects.
node_modules,.git, build caches, and dependency folders create thousands of file changes during a normal workday. iCloud tries to sync each one, spiking CPU and disk usage. - Large media files. RAW photos, video projects, and audio samples can be hundreds of megabytes each. Syncing them to iCloud eats bandwidth and storage.
- Sensitive files. Some files should never leave your local machine. Private keys, credentials, environment files, and local databases are not cloud backup candidates.
- Folders with high churn. Anything that changes frequently — logs, temp files, cache directories — creates constant sync activity for no real benefit.
The goal is not to turn iCloud off forever. The goal is to keep iCloud useful while keeping the wrong folders out of it.
Method 1: Move folders outside iCloud Drive
The simplest approach is to keep your important folders outside iCloud's sync scope entirely. iCloud Drive syncs the contents of ~/Documents and ~/Desktop (if you have Desktop & Documents sync enabled). It also syncs any folder you explicitly move into iCloud Drive through Finder.
If your projects live in ~/Developer, ~/Code, or another folder you created yourself, iCloud is not watching them. You do not need to do anything — they are already excluded.
# Check if your folder is inside iCloud Drive
ls -la ~/Library/Mobile\ Documents/com~apple~CloudDocs/
# If it's there, move it to a local-only location
mkdir -p ~/Developer
mv ~/Library/Mobile\ Documents/com~apple~CloudDocs/my-project ~/Developer/This is the least clever method, which is why I like it. It works on every macOS version and does not depend on hidden iCloud behavior. The tradeoff is obvious: those files will not appear on your other Apple devices. For code projects, that is often the point.
Method 2: Use .nosync marker files
iCloud Drive has an undocumented behavior: if you create a file called .nosync inside any folder, iCloud stops syncing that folder and its contents. This is not an official Apple feature, but it has worked consistently across macOS versions.
# Create a .nosync file in any folder you want excluded
touch ~/Documents/projects/my-app/node_modules/.nosync
# Or create it proactively after npm install
npm install && touch node_modules/.nosyncThe appeal is obvious: no moving folders, no settings screen, no extra app. The downsides are just as obvious:
- It is undocumented. Apple could remove this behavior in any macOS update without warning.
- You have to place the file in every folder you want excluded. After deleting and recreating
node_modules, you need to add it again. - It only works with iCloud Drive. Dropbox, Google Drive, and other providers do not respect this marker.
For a quick fix in the middle of a project, .nosync is handy. As a long term habit, it is fragile. We covered this approach in more detail in our guide on syncing node_modules without freezing your Mac.
Method 3: Disable Desktop & Documents sync
If you do not want iCloud to sync your entire Desktop and Documents folders, you can turn off the feature in System Settings:
- Open System Settings → Apple ID → iCloud
- Click iCloud Drive
- Toggle off Desktop & Documents Folders
This stops iCloud from syncing everything in those two directories. Your files remain on your Mac — iCloud does not delete them. But you will lose access to those files from other Apple devices, and any files already synced to iCloud will stay there until you manually remove them.
This is the big switch. If your projects live in ~/Documents or on your Desktop, they stop following you to other Apple devices. For some people that is perfect. For others it is too blunt.
Method 4: Use Lsyncer for filtered sync
The first three methods are about keeping folders out of iCloud. But what if you still want a cloud backup — just not of everything? What if you want to sync source files and configs to iCloud while keeping node_modules, .git, and build caches local?
That is what Lsyncer does. It creates a filtered copy of your project in a destination you choose, including iCloud Drive. Your source folder can stay local. The iCloud copy gets the files worth backing up, not the dependency pile.
Source: ~/Developer/my-app
Dest: ~/Library/Mobile Documents/com~apple~CloudDocs/Backups/my-app
Skip: node_modules, .git, dist, .next, coverageYou get a cloud backup of your actual work — source files, configs, documentation — without the thousands of dependency files that freeze your Mac. The sync runs on a schedule you choose, and you can see exactly what was synced in the app dashboard.
It is a one-time $19.99 purchase on the Mac App Store. No subscription, no cloud account beyond the one you already have.
Which method should you use?
| Method | Effort | Reliability | Keeps iCloud for other files | Best for |
|---|---|---|---|---|
| Move outside iCloud | Low | High | Yes | Projects that never need cloud access |
.nosync markers |
Low | Medium (undocumented) | Yes | Quick fixes, one-off exclusions |
| Disable Desktop & Documents | Low | High | No (broad change) | People who never want those folders in iCloud |
| Lsyncer | Low | High | Yes | Filtered backup of source files to iCloud or elsewhere |
The setup I like is simple: keep projects in ~/Developer, outside iCloud. Use Lsyncer to create filtered backups to an external drive or a specific iCloud folder. Keep .nosync around for the occasional emergency. No single trick has to carry the whole workflow.
Frequently asked questions
Will iCloud delete my files if I turn off Desktop & Documents sync?
No. Turning off the sync feature stops iCloud from watching those folders, but the files remain on your Mac. Files that were already synced to iCloud will stay on Apple's servers until you manually delete them, but your local copies are untouched.
Can I use .nosync with Dropbox or Google Drive?
No. The .nosync file only works with iCloud Drive. Dropbox uses .dropbox_ignore (which works differently), and Google Drive has no equivalent mechanism. Each provider handles exclusions differently.
Is there a way to exclude only node_modules from iCloud?
Not through official iCloud settings. Apple does not offer per-folder exclusion for iCloud Drive. Your best options are the .nosync marker file inside node_modules, moving your projects outside ~/Documents, or using a tool like Lsyncer to sync a filtered copy.
Does Lsyncer sync directly to iCloud?
Lsyncer syncs to any destination folder, including folders inside iCloud Drive. You can set a filtered copy of your project to sync to an iCloud-backed location while skipping node_modules, .git, and build caches. For more details, see our guide on why iCloud freezes your Mac when syncing node_modules.
Can I exclude subfolders from iCloud without turning off the whole feature?
Yes. The .nosync marker lets you exclude specific subfolders without affecting the rest of iCloud Drive. Place a file called .nosync in the folder you want excluded, and iCloud will skip it.
Related reading
- How to sync node_modules without freezing your Mac — five solutions ranked from free to paid
- ChronoSync vs Lsyncer — which Mac sync tool fits your workflow
- Why iCloud freezes your Mac when syncing node_modules — the root cause explained
Take control of what iCloud syncs
iCloud Drive is useful. It is just not a precise developer sync tool. Excluding the right folders is not a hacky obsession; it is how you stop a good consumer feature from wrecking a professional workflow.
Start with the simplest method that fits. If you need a filtered backup that keeps source files in the cloud and leaves dependencies local, Lsyncer gets you there without turning the whole Mac into a settings project.
Get Lsyncer on the Mac App Store — $19.99, one-time purchase.