LSyncer icon LSyncer
macOS Development

iCloud Drive Stuck Uploading on Mac: How Developers Can Clear the Queue

iCloud Drive stuck uploading on Mac? Clear the queue, find developer folders causing churn, and prevent node_modules from blocking sync.

Mac developer frustrated by an iCloud Drive upload queue stuck on thousands of tiny project files

iCloud Drive stuck uploading on Mac is annoying for anyone. For developers, it can be worse: the upload count never reaches zero, Finder keeps saying it is processing items, and the Mac feels busy even when you are only editing code. The usual trigger is not one huge file. It is a project folder full of small files that iCloud has to scan, hash, upload, and reconcile one by one.

If the stuck upload started after npm install, pip install, a branch switch, a build, or a framework cache refresh, assume iCloud is drowning in file churn before you assume your Apple ID is broken. This guide gives you a practical way to diagnose the queue, clear the immediate blockage, and change the workflow so it does not come back next week.

Why iCloud Drive stuck uploading on Mac happens with code projects

iCloud Drive is good at syncing documents. It is much less happy with active development folders because developer tools write huge numbers of small files very quickly. A single dependency install can create more filesystem events than a month of normal document editing.

Common offenders:

  • node_modules, especially large JavaScript or TypeScript projects with nested packages.
  • .git, where objects, refs, lock files, and indexes change during fetches, rebases, commits, and branch switches.
  • .venv, venv, vendor/bundle, and other language dependency directories.
  • .next, dist, build, coverage, target, DerivedData, and test caches.

The file count matters more than the folder size. A 90 MB dependency tree with 45,000 files can be harder on a sync engine than a single 2 GB video. iCloud has to notice each file, inspect metadata, decide what changed, coordinate with cloud state, and recover if the local folder keeps changing while the upload queue is still running.

Check what iCloud is trying to upload

Start by identifying whether the stuck queue overlaps with an active project. In Finder, click the iCloud status icon if it appears. Sometimes macOS shows the folder or file currently waiting. If Finder only gives you a vague number, use Terminal to inspect the file counts in the project you suspect.

cd ~/Library/Mobile\ Documents/com~apple~CloudDocs
find . -name node_modules -type d -prune -print
find . -name .git -type d -prune -print
find . \( -name .next -o -name dist -o -name build -o -name coverage \) -type d -prune -print

If your code lives in a different iCloud Drive folder, adjust the path. The default iCloud Drive location is usually:

~/Library/Mobile Documents/com~apple~CloudDocs

Once you find a likely project, count the generated files. These commands are rough but useful:

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

Numbers in the tens of thousands explain a lot. They do not prove iCloud is broken. They prove you handed iCloud a workload it was not designed for.

Confirm the stuck upload is iCloud, not your build tool

Open Activity Monitor and sort by CPU. On recent macOS versions, the processes involved with iCloud and file sync can include bird, cloudd, and fileproviderd. Spotlight may join the party with mds or mdworker if it is indexing the same changing tree.

You can also check from Terminal:

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

If node, python, ruby, cargo, or xcodebuild is the top process, iCloud may only be reacting to ongoing work. Stop the build or package install first. If the dev tool is quiet but iCloud processes keep working and Finder still says it is uploading items, focus on the sync queue.

How generated project files make iCloud Drive uploads stick A package manager creates many files, macOS emits file events, iCloud builds an upload queue, and new file changes keep invalidating previous work. dev tool installs packages or rebuilds cache iCloud queue scan, hash, upload stuck new changes keep feeding the queue
iCloud can finish ordinary uploads. It struggles when generated folders keep changing faster than the queue drains.

Fix 1: pause the churn before you reset anything

Do not start by killing random daemons. First stop the thing that keeps creating new work. Quit dev servers, test watchers, bundlers, Docker containers, package installs, and IDE indexing if they are touching the iCloud folder. If a project is under iCloud Drive, close it in your editor for a minute so background language servers stop scanning and writing caches.

Then wait. That sounds unsatisfying, but it matters. If the queue is only large, not corrupt, iCloud may catch up once the folder stops changing. Give it a clean window before you make the situation harder to reason about.

Fix 2: remove generated folders from the iCloud copy

If the queue is clearly tied to a development folder, delete the generated directories from the iCloud copy. Keep source files, lockfiles, documentation, and configuration. Remove files you can rebuild.

For a Node.js project:

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 important part is where you recreate those directories. If you reinstall them inside iCloud Drive, the upload queue may start again. Use this step to calm iCloud down, then move the active project somewhere local.

Abstract bottleneck of thousands of generated development files entering a cloud upload queue
The stuck upload is often a file-count problem. Every tiny generated file becomes another sync decision.

Fix 3: move active projects out of iCloud Drive

The most reliable fix is boring: do not develop inside iCloud Drive. Create a local workspace and move active repositories there.

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 source history. iCloud can still store exported documents, design files, notes, and archived zip files. It just should not be responsible for a live dependency tree.

If you need a copy of the project in iCloud, copy a filtered version instead of the working tree. That means source code yes, generated directories no.

Fix 4: use .nosync carefully

macOS has a convention where files or folders ending in .nosync are not synced by iCloud Drive. This can be useful for local scratch folders inside an iCloud project:

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

Be careful with dependency folders. Renaming node_modules to node_modules.nosync breaks normal Node.js module resolution unless you add symlinks or custom tooling. That is usually more fragile than moving the project out of iCloud or using a filtered sync workflow.

Use .nosync for folders you control. Do not use it as a clever replacement for a clean project layout.

Fix 5: sync a filtered project backup instead of the live working tree

If you want a backup or second copy, sync only the files worth preserving. rsync can do that from Terminal:

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 if you use --delete:

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

Read the output. Make sure the source and destination are exactly what you intended. A filtered sync workflow is powerful, but a typo with --delete can remove files at the destination.

Where Lsyncer fits

Lsyncer is for developers who want that filtered sync workflow without keeping a long rsync command in a notes file. 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 will not repair iCloud Drive or turn it into a developer-aware cloud filesystem. The healthier pattern is simpler: keep active projects local, sync a clean copy where you want it, and leave generated files on the machine that generated them.

Use Lsyncer when

  • You want a clean project backup without dependency folders.
  • You prefer a macOS GUI over scripts and cron jobs.
  • You want scheduled sync with visible status.
  • You want a one-time purchase instead of another subscription.

Skip it when

  • You need collaborative cloud storage with conflict resolution.
  • You intentionally want every generated file mirrored.
  • You already maintain a tested rsync setup and like it.
  • You need team sharing, comments, or permissions.
Organized filtered sync workflow where source files are backed up and generated dependency folders stay local
A filtered backup keeps the useful parts of a project without asking iCloud to process disposable build output.

Best practices to prevent stuck iCloud uploads

  • Keep active repositories in ~/Developer or ~/Code. Treat iCloud Drive as a destination for selected copies, not the place where package managers write all day.
  • Back up lockfiles, not installed packages. Keep package-lock.json, pnpm-lock.yaml, yarn.lock, requirements.txt, pyproject.toml, and Gemfile.lock. Rebuild dependencies from them.
  • Do not sync live .git directories through iCloud. Use Git remotes for history. If you need a file backup, exclude .git and rely on the remote repository for commits.
  • Watch file counts. When a folder has 50,000 files, the sync cost is not obvious from Finder's size column.
  • Use dry runs before filtered deletes. Any sync command that can delete files deserves a test pass.

Related reading

FAQ

Why is iCloud Drive stuck uploading on my Mac?

For developers, the common cause is a folder with thousands of generated files. iCloud Drive has to process each file and its metadata. node_modules, .git, virtual environments, and build caches can keep the upload queue busy or make it appear stuck.

Can I force quit bird or cloudd to fix a stuck upload?

You can force quit them and macOS will usually restart them, but that only restarts the sync engine. If the same project folder still contains thousands of changing files, the queue often returns. Stop the file churn and remove generated folders first.

Is it safe to delete node_modules from iCloud Drive?

Usually yes, if it belongs to a Node.js project and you still have the source code plus a lockfile such as package-lock.json, pnpm-lock.yaml, or yarn.lock. Recreate dependencies with your package manager outside iCloud Drive.

Does .nosync stop iCloud from uploading a folder?

Folders ending in .nosync are generally excluded from iCloud sync. It works best for scratch folders you control. It is not a clean fix for node_modules because package managers expect that exact folder name.

Should developers use iCloud Drive for code projects?

iCloud Drive is fine for documents and occasional project archives. For active coding, it is usually better to keep repositories local, use Git for history, and sync a filtered backup that excludes generated dependencies, build output, and caches.