Composer Cache on Mac: Is It Safe to Clear?
Medium riskPackage managers & build toolsUpdated
- Location
~/Library/Caches/composer
- Risk level
- Medium riskSafe to remove, but the tool that owns it re-downloads or rebuilds it on next use, which costs time and bandwidth. Listed, never pre-selected.
- Selected by default
- No — you choose whether to include it
- What Freshist does
- Moves the selected items to the Trash, so you can undo. Nothing is deleted outright.
- In the app
- Clean → Composer Cache — “PHP dependency cache — Composer re-downloads packages on next install.”
From Freshist's own cleaning rules — the same catalog the app uses.
What lives in the Composer cache
Composer, PHP's dependency manager, keeps a shared cache so the same package isn't downloaded twice. According to the Composer configuration docs, the default cache-dir on macOS is /Users/<user>/Library/Caches/composer.
Inside it, Composer separates three kinds of data:
| Subfolder | What it holds | Config key |
|---|---|---|
files/ | Zip archives of package releases ("dist" files) | cache-files-dir |
repo/ | Repository metadata, such as the package lists from Packagist | cache-repo-dir |
vcs/ | Git clones for packages installed from source | cache-vcs-dir |
None of it is project code. Composer copies or extracts from here into each project's vendor/ folder.
Composer's own cleanup, and its limits
Composer already runs a garbage collection. The docs list two limits: cache-files-ttl, which purges unused dist files after six months by default, and cache-files-maxsize, which trims the files cache to 300MiB, removing the least-used files first.
Those limits only apply to the files/ cache. Repository metadata and VCS clones aren't size-capped the same way, so a Mac that installs many packages from source (--prefer-source, or dev branches) can carry large vcs/ clones. Laravel, Symfony or Drupal projects with long dependency lists make the metadata grow too.
What happens if you clear it
- The next
composer installorcomposer updatedownloads archives again, which takes longer on big projects. composer.lockstill decides which versions you get, so nothing changes in your dependency tree.- Existing
vendor/folders keep working. - Global settings and authentication in
auth.jsonandconfig.jsonlive in Composer's home directory, not the cache, so you stay logged in to private repositories.
Check the path and size
composer config --global cache-dir # the cache path in use
du -sh "$(composer config --global cache-dir)"
du -sh ~/Library/Caches/composer/* # files, repo and vcs sizes
On a default macOS install, composer config --global cache-dir prints ~/Library/Caches/composer. If it prints something else, that's the folder to look at.
Clear it with Composer
composer clear-cache
clearcache and cc are aliases. The command is documented in the Composer CLI reference and empties the whole cache directory. The --gc option runs only the garbage collection (applying the TTL and size limits) instead of wiping everything. Older releases lack it, so check composer clear-cache --help first.
To skip the cache for a single run instead of clearing it, pass the global --no-cache option, which the docs describe as equivalent to setting COMPOSER_CACHE_DIR=/dev/null.
Reasons to keep it
Keep it if you work offline, switch between projects that share many packages, or depend on private repositories that are slow to fetch. Clear it when an install pulls a corrupt archive, when you've left PHP work behind, or when vcs/ has grown large from source installs. For the same idea in other ecosystems, see the npm cache and Gradle cache guides.
Sources
Frequently asked questions
Does composer clear-cache affect vendor/ in my project?
No. vendor/ is the installed copy inside each project. The cache command only empties Composer's shared cache directory.
Why is my cache somewhere other than ~/Library/Caches/composer?
If COMPOSER_HOME or COMPOSER_CACHE_DIR is set, or you upgraded from an old Composer 1 setup that used ~/.composer, the cache can live elsewhere. composer config --global cache-dir prints the path in use.
Can I stop the cache from growing so large?
Yes. Lower cache-files-maxsize (default 300MiB) or cache-files-ttl (default six months) in your global config. Composer trims the file cache to those limits during its periodic garbage collection.