Force iCloud Drive Sync on Mac: A Developer’s Fix Guide

Mac developer frustrated by an iCloud Drive sync queue stalled on a busy code project

Force iCloud Drive sync on Mac sounds like it should be a button. You save a file, Finder says “waiting,” and you want macOS to stop thinking and upload the thing now. The uncomfortable answer is that iCloud Drive has no official “sync now” command like Git, rsync, or Dropbox used to expose. What you can do is trigger a rescan, remove the blockers that keep the queue busy, and give iCloud a smaller job it can finish.

For developers, that distinction matters. If iCloud is stuck after npm install, a branch switch, pip install, a build, or a test run, forcing another sync pass can make the queue worse. The problem is rarely one missing upload. It is usually thousands of tiny generated files changing faster than iCloud can scan, hash, reconcile, and upload them.

How to force iCloud Drive sync on Mac without making the queue worse

Start with the least destructive actions. Do not sign out of iCloud, delete CloudDocs data, or kill random daemons as the first move. Those steps can trigger a full re-index of the account and create a much larger sync job than the one you were trying to fix.

Stop active writers. Quit dev servers, test watchers, package installs, Docker containers, IDE indexing, and anything else touching the project inside iCloud Drive.
Check whether Finder still sees a queue. Open iCloud Drive in Finder and look for status icons beside folders. If the count is moving, let it finish.
Create one small test file. Add a tiny file such as icloud-sync-test.txt, wait a minute, then delete it. This nudges Finder and iCloud Drive without dumping more generated files into the queue.
Toggle network only if the queue is idle. Briefly disconnect and reconnect Wi-Fi. This can wake a stale connection, but it will not fix a folder that is still producing thousands of changes.
Restart the Mac before deeper resets. A normal restart is safer than manually deleting caches or signing out of iCloud.

If those steps work, you had a stale sync state. If they do not, assume the folder contents are the problem. That is especially likely when the stuck folder is a JavaScript, Python, Ruby, Rust, Swift, or web app project.

Why “sync now” fails on developer folders

iCloud Drive is designed around human document workflows: edit a Pages file, save a PDF, move a photo, rename a folder. A developer workspace behaves differently. It can create or delete tens of thousands of files in seconds, and many of those files are disposable implementation detail.

Examples that confuse generic sync engines:

node_modules after npm install, pnpm install, or yarn install.
.git objects, refs, lock files, and indexes during fetches, rebases, branch switches, and commits.
.venv, venv, vendor/bundle, and package caches for Python and Ruby projects.
.next, dist, build, coverage, target, DerivedData, and test caches.
Log files, temporary databases, local uploads, generated thumbnails, and framework hot-reload artifacts.

The file count hurts more than the byte count. A single 1 GB video is large, but it is one item. A 140 MB dependency tree with 60,000 files is 60,000 metadata decisions, file events, hashes, upload attempts, conflict checks, and potential retries. If your editor or dev server keeps changing files while iCloud is still processing the last batch, the queue never gets a quiet moment.

A forced rescan only helps after the project stops changing. If generated files keep appearing, iCloud is being given new work faster than it can finish the old work.

Check whether iCloud Drive is stuck or just busy

Before you reset anything, decide which situation you are in. “Busy” means the queue is ugly but still moving. “Stuck” means the same item count or same folder state persists after the project is quiet and the network is available.

Use Finder first. Open iCloud Drive and inspect the folder with the cloud icon, dotted progress circle, or “waiting” state. If the status jumps around different project subfolders, you probably have file churn. If it sits on one ordinary document for a long time, you may have a stale file or network issue.

Then check whether macOS is spending CPU on sync processes:

ps aux | egrep 'bird|cloudd|fileproviderd|mds|mdworker' | grep -v grep

Those process names can vary by macOS version, but the pattern is useful. If fileproviderd, bird, or cloudd is active while Finder shows progress, iCloud is probably working. If node, python, ruby, cargo, xcodebuild, or an IDE helper is the busy process, iCloud may only be reacting to your tools.

For a suspect project, count the generated files:

find node_modules -type f 2>/dev/null | wc -l
find .git -type f 2>/dev/null | wc -l
find .venv venv vendor/bundle -type f 2>/dev/null | wc -l
find .next dist build coverage target -type f 2>/dev/null | wc -l

If those commands return tens of thousands of files, the “force sync” problem is really a project layout problem.

Abstract bottleneck showing many tiny generated developer files jamming a cloud sync pipeline — The hard part is not uploading code. It is asking iCloud to track every disposable dependency, cache, and build artifact as if it were a document.

Fix 1: force a small iCloud Drive rescan safely

Use this when the folder is quiet and you only need to wake a stale sync state.

Quit the app that last wrote to the folder.
Create a tiny file in the iCloud Drive folder:

cd ~/Library/Mobile\ Documents/com~apple~CloudDocs
printf 'sync test\n' > icloud-sync-test.txt

Wait for the file to appear on another device or at icloud.com/iclouddrive.
Delete it after the test:

rm icloud-sync-test.txt

This does not guarantee a full queue flush. It does give iCloud a simple new event and a way to prove whether syncing is alive. If the test file syncs but your project does not, the project contents are the problem.

Fix 2: remove generated folders from the iCloud copy

If a developer folder is blocking iCloud, remove files you can rebuild. Keep source files, lockfiles, config, docs, and hand-authored assets. Delete dependency folders and generated output from the iCloud-backed copy.

For Node.js:

rm -rf node_modules .next dist build coverage .turbo .cache
npm install

For Python:

rm -rf .venv venv __pycache__ .pytest_cache .mypy_cache .ruff_cache
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For Ruby:

rm -rf vendor/bundle .bundle tmp/cache log/*.log
bundle install

The rebuild commands are shown to make the point: those folders are reproducible. Do not recreate them inside iCloud Drive if you are trying to clear the queue. Rebuild them in a local workspace outside iCloud.

Fix 3: move active projects out of iCloud Drive

The most reliable way to force iCloud Drive sync on Mac is to stop using iCloud Drive as the active working directory for code. Put live repositories somewhere local, then sync a clean copy elsewhere.

mkdir -p ~/Developer
mv ~/Library/Mobile\ Documents/com~apple~CloudDocs/my-app ~/Developer/my-app

After the move, open the project from ~/Developer, reinstall dependencies there, and let Git handle history. iCloud can still hold exported builds, notes, archives, or a filtered backup. It just should not own a live dependency tree.

Fix 4: use `.nosync` only for folders you control

macOS recognizes a convention where files or folders ending in .nosync are not synced by iCloud Drive. This can help for local scratch areas:

mkdir tmp.nosync
mkdir local-db.nosync
mkdir generated-exports.nosync

Be careful with dependency folders. Renaming node_modules to node_modules.nosync breaks normal Node module resolution unless you add symlinks or custom package manager configuration. That kind of cleverness usually costs more time than it saves.

Use .nosync for directories your own scripts control. For standard dependency folders, the cleaner fix is to keep the repo outside iCloud or sync a filtered copy.

Fix 5: sync a clean backup instead of the live project

If the real goal is backup, not real-time cloud collaboration, copy only the files worth preserving. rsync is the classic Terminal option:

rsync -av --delete \
  --exclude 'node_modules/' \
  --exclude '.git/' \
  --exclude '.venv/' \
  --exclude 'venv/' \
  --exclude 'vendor/bundle/' \
  --exclude '.next/' \
  --exclude 'dist/' \
  --exclude 'build/' \
  --exclude 'coverage/' \
  --exclude '.cache/' \
  ~/Developer/my-app/ \
  ~/Library/Mobile\ Documents/com~apple~CloudDocs/Backups/my-app/

Run a dry run first, especially with --delete:

rsync -avn --delete --exclude 'node_modules/' ~/Developer/my-app/ ~/Backups/my-app/

Read the output. Make sure the source and destination are correct. A filtered sync is healthy because the backup stays boring: source code, lockfiles, docs, assets, and configuration. No dependency junk. No build cache churn. No hidden queue of disposable files.

Good things to sync

src, app, lib, public, docs, and hand-written assets.
package.json, lockfiles, pyproject.toml, Gemfile, and config files.
Deployment manifests, scripts, notes, and project-specific data you cannot recreate.

Bad things to sync

node_modules, virtual environments, package caches, and vendored dependencies.
.git if a remote already protects source history.
dist, build, .next, coverage, logs, temp files, and test caches.

Organized filtered developer backup where source files sync cleanly and generated folders stay local — A clean backup syncs the files you authored and leaves rebuildable dependency folders on the Mac that generated them.

Where Lsyncer fits

Lsyncer is for Mac developers who want the filtered-backup pattern without maintaining a long rsync command. It is a native macOS app that syncs selected folders while skipping the usual development junk: node_modules, .git, virtual environments, build output, and caches.

It does not force Apple’s iCloud servers to behave differently, and it is not a collaboration platform. The healthier workflow is: keep active projects local, use Git for source history, and sync a clean copy to a folder or drive you choose. Lsyncer makes that workflow visible, scheduled, and less error-prone. It is $19.99 once, not another subscription.

Best practices to prevent iCloud Drive sync stalls

Keep live code local. Use ~/Developer, ~/Code, or ~/Projects for active repositories.
Let Git do Git’s job. iCloud Drive is not a replacement for source history, branches, review, or remotes.
Sync filtered backups. Back up source and config, not dependency trees and build artifacts.
Watch file count. A “small” project can still be expensive if it contains 80,000 files.
Make sync quiet. Schedule backups after installs, builds, and test runs, not while watchers are actively writing.

The goal is not to abandon iCloud Drive. The goal is to stop treating it like a developer-aware filesystem. Give iCloud a stable set of files, and it usually behaves. Give it a live dependency tree, and no force-sync trick will save the afternoon.

FAQ: force iCloud Drive sync on Mac

Is there a command to force iCloud Drive sync on Mac?

Apple does not provide a supported icloud sync now command. The safest practical options are to stop file churn, create a tiny test file in iCloud Drive, restart the Mac if the queue is stale, and remove generated folders that keep the queue busy.

Why does iCloud Drive get stuck after npm install?

npm install can create tens of thousands of files in node_modules. iCloud Drive tries to process those files individually. If the project keeps changing while iCloud is scanning and uploading, the queue can look stuck even though the sync engine is working.

Does .gitignore stop iCloud from syncing node_modules?

No. .gitignore only affects Git. iCloud Drive does not read your Git ignore rules. Put generated folders outside iCloud Drive, use .nosync for folders you control, or sync a filtered backup with explicit exclusions.

Should I kill bird, cloudd, or fileproviderd?

Usually no. A normal restart is safer and easier to reason about. Killing sync processes can hide the real issue and may trigger extra scanning. Stop developer tools first, then restart the Mac if Finder’s iCloud state remains stale.

What is the best backup workflow for Mac code projects?

Use Git for history, keep active repositories local, and maintain a filtered backup that excludes dependencies, virtual environments, build output, caches, logs, and .git when appropriate. You can do that with rsync or a developer-focused app like Lsyncer.