iCloud Drive Not Syncing on Mac: A Developer’s Fix Guide

iCloud Drive not syncing on Mac is usually described like a consumer file problem: restart, sign out, sign back in, wait. That advice is fine when the missing file is a PDF. It is incomplete when the folder is an active software project with node_modules, .git, .venv, build caches, logs, coverage reports, and a watcher rewriting files every few seconds.

For developers, iCloud can look broken even when the service is technically working. One file appears on another Mac, another stays stuck in Finder, a folder says “sync pending,” and Activity Monitor shows bird, cloudd, or fileproviderd doing real work without visible progress. The sync engine is not just uploading bytes. It is tracking a fast-moving graph of small files, metadata changes, deletes, renames, and conflicts.

This guide walks through how to diagnose the problem, how to get iCloud unstuck safely, and how to prevent developer folders from creating the same queue again. The short version: keep active repositories local, sync clean copies, and exclude generated folders that can be rebuilt.

Why iCloud Drive not syncing on Mac often starts with developer file churn

iCloud Drive is optimized for documents, photos, desktop files, and normal user data. Those folders change at human speed. Development folders change at tool speed. A single npm install can create tens of thousands of files. A branch checkout can rewrite a working tree and update Git internals. A test run can fill coverage and cache directories. A dev server can rewrite .next, dist, or temporary build artifacts many times per minute.

When those folders live inside iCloud Drive, macOS has to observe the changes, update file-provider state, calculate metadata, decide what should be uploaded or downloaded, handle conflicts, and keep Finder badges current. The queue can fall behind even if your internet is fast.

The usual suspicious folders are:

• node_modules from npm, pnpm, Yarn, Vite, Next.js, Astro, and other JavaScript tooling.
• .git, especially during rebases, large branch switches, submodule updates, or generated lockfile churn.
• .venv, venv, __pycache__, .pytest_cache, .mypy_cache, and notebook checkpoints in Python projects.
• vendor/bundle, tmp/cache, and log directories in Ruby projects.
• dist, build, .next, .nuxt, target, coverage, .turbo, and similar build output.

Step 1: check whether iCloud is stuck or just overloaded

Start with the boring checks, because they separate account problems from workload problems:

• Open System Settings → Apple ID → iCloud → iCloud Drive and confirm iCloud Drive is enabled.
• Check Apple's system status page if every device has stopped syncing at once.
• Make sure the Mac has enough free disk space. Low local storage can block downloads and evictions.
• Open Finder and look for cloud icons, “waiting to upload,” “sync pending,” or repeated download indicators.

Then check the iCloud-related processes. In Activity Monitor, sort by CPU and Network. From Terminal:

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

Some CPU usage is normal while sync is catching up. The important question is whether the same developer directories keep feeding it new work. Run these commands from the project root:

find node_modules -type f 2>/dev/null | wc -l
find .git -type f 2>/dev/null | wc -l
find .venv venv -type f 2>/dev/null | wc -l
find .next dist build coverage target .turbo -type f 2>/dev/null | wc -l
find . -type f -mmin -10 | head -50

If the counts are huge, or the recently modified files are mostly caches and generated output, you are not looking at a random iCloud outage. You are syncing the wrong parts of the project.

Step 2: stop active writers before restarting services

If a dev server, test watcher, build watcher, package installer, or local database is writing into an iCloud-backed folder, pause it first. Restarting iCloud while the project continues to generate events is like clearing a traffic jam while more cars keep entering the tunnel.

Stop commands such as:

• npm run dev, next dev, vite, webpack, Parcel, or Astro watchers.
• Jest, Vitest, Playwright, Cypress, or coverage watch modes.
• Python notebooks, local databases, or scripts writing output under the repository.
• Any process writing logs, screenshots, reports, or generated assets into the synced tree.

After the writers stop, give iCloud a few minutes. If files start moving, the queue was overloaded rather than permanently broken. If nothing changes, rebooting the Mac is reasonable. Use sign-out/sign-in only as a last resort, because it can trigger a large re-scan and make the queue temporarily worse.

Step 3: move active repositories out of iCloud Drive

The most reliable fix is to stop developing inside iCloud Drive. Keep active code under a plain local directory:

~/Developer
~/Code
~/Projects

Use GitHub, GitLab, Bitbucket, or your own remote for source history. Use iCloud for documents and clean exports, not live dependency trees. This avoids the core mismatch: development tools expect a low-latency local filesystem, while iCloud expects files that change slowly enough to reconcile.

If your current project is inside ~/Library/Mobile Documents/com~apple~CloudDocs or an iCloud-synced Desktop/Documents folder, move it carefully:

mkdir -p ~/Developer
cp -a ~/Library/Mobile\ Documents/com~apple~CloudDocs/Projects/my-app ~/Developer/my-app

Open the copied project, run tests, reinstall dependencies if needed, and only then remove or archive the iCloud copy. Do not delete the iCloud version until you have confirmed the local copy contains the source files you need.

Step 4: clean generated folders before creating a synced copy

Sometimes you still want a copy of the project in iCloud or on an external drive. That copy should usually contain source code, configuration, lockfiles, docs, and assets. It should not contain generated dependencies and build output.

For Node.js projects, clean the generated folders before syncing:

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

The npm install step belongs in your active local working copy, not in the synced copy. The synced copy should be something you can restore and rebuild, not a live mirror of every cache.

For Python:

rm -rf .venv venv __pycache__ .pytest_cache .mypy_cache .ruff_cache
python3 -m venv .venv

For Ruby:

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

Step 5: use filtered sync instead of raw iCloud Drive for code backups

If your goal is backup rather than real-time cloud collaboration, filtered sync is a better model. rsync is a good baseline because it can copy the important parts of a project while excluding the noisy parts:

rsync -av --delete \
  --exclude 'node_modules/' \
  --exclude '.git/' \
  --exclude '.venv/' \
  --exclude 'venv/' \
  --exclude '.next/' \
  --exclude 'dist/' \
  --exclude 'build/' \
  --exclude 'coverage/' \
  ~/Developer/my-app/ ~/Backups/my-app/

Run a dry run first, especially when using --delete:

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

That is the developer-friendly pattern: source files and project configuration are copied, generated junk is skipped, and the destination stays useful without becoming a second live development environment.

Where Lsyncer fits when iCloud Drive is not syncing on Mac

Lsyncer is built for developers who want the filtered-sync approach without maintaining shell scripts. It is a native macOS app for syncing folders while skipping common development junk such as node_modules, .git, virtual environments, build folders, and caches. You choose the source, destination, exclusions, and schedule.

It is not trying to turn iCloud Drive into a perfect real-time collaboration system. The healthier workflow is simpler: keep active repositories local, use Git for source history, and sync a clean project copy to wherever you want backups. Lsyncer gives that workflow a visible macOS interface, status, schedules, and a one-time $19.99 price instead of another subscription.

If you are comparing options, these related guides may help:

• iCloud sync too slow on Mac — how to diagnose file-count bottlenecks and slow queues.
• How to stop iCloud from syncing certain folders — practical exclusion patterns and .nosync trade-offs.
• Best rsync alternative for Mac developers — when scripts are enough and when a GUI is less fragile.

Best practices to prevent iCloud Drive sync problems in developer workflows

• Keep live repos local. Put active projects in ~/Developer, ~/Code, or ~/Projects, not in iCloud Drive.
• Use Git for source history. iCloud is not a replacement for version control or code review.
• Exclude rebuildable folders. Dependency directories, virtual environments, caches, and build output should be recreated from lockfiles and config.
• Watch file count, not just bytes. A tiny folder can still be expensive if it contains tens of thousands of files.
• Keep synced copies boring. A backup copy should be stable, restorable, and easy to inspect. It should not run dev servers or package installs.

The goal is not to never use iCloud Drive. The goal is to stop asking it to do the one workload it handles poorly: high-churn developer folders full of tiny generated files.

FAQ: iCloud Drive not syncing on Mac for developers

Why is iCloud Drive not syncing my Mac project folder?

If the project contains node_modules, .git, virtual environments, build output, or caches, iCloud may be overloaded by file events rather than truly offline. Stop active writers, check iCloud processes, and count files in generated directories before changing account settings.

Should I put node_modules in iCloud Drive?

No. node_modules is rebuildable from package.json and a lockfile, and it often contains tens of thousands of files. Sync the source and lockfiles, then run npm install, pnpm install, or yarn install on each machine.

Does .gitignore stop iCloud from syncing files?

No. .gitignore affects Git, not iCloud Drive. A folder ignored by Git can still be uploaded by iCloud unless it is outside iCloud Drive or excluded by a separate sync workflow.

Is it safe to restart iCloud Drive services?

Restarting the Mac is usually safer than manually killing sync processes. Before restarting anything, stop dev servers and watchers so the queue can drain. Signing out of iCloud should be a last resort because it can trigger a large re-scan.

What is the best way to back up code projects on Mac?

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