Composer "Cannot create cache directory" permission error in CI

Composer writes downloaded archives and metadata to a cache under COMPOSER_HOME. When that directory cannot be created or written, often a permissions clash in a container, Composer warns and proceeds without cache, which slows every run.

What this error means

composer install prints "Cannot create cache directory /home/.../.composer/cache/files/, or directory is not writable. Proceeding without cache", or fails outright when it also cannot write vendor.

composer

Cannot create cache directory /var/www/.composer/cache/repo/https---repo.packagist.org/,
or directory is not writable. Proceeding without cache.
In Filesystem.php line 254:
  /var/www/.composer/cache: failed to create directory

Common causes

COMPOSER_HOME owned by a different user

The container runs composer as a user that lacks write access to the default cache path created by root in the image.

A read-only or unset HOME in the job

When HOME is unset or read-only, Composer cannot derive or create a writable cache directory.

How to fix it

Point cache at a writable directory

Set COMPOSER_HOME (and COMPOSER_CACHE_DIR) to a path the job user can write.

.github/workflows/ci.yml

env:
  COMPOSER_HOME: ${{ runner.temp }}/composer
  COMPOSER_CACHE_DIR: ${{ runner.temp }}/composer-cache

Fix ownership in a container image

Create and chown the cache path for the runtime user when building a custom image.

Dockerfile

RUN mkdir -p /var/www/.composer && chown -R www-data:www-data /var/www/.composer

How to prevent it

Set COMPOSER_HOME to a writable, job-scoped path in CI.
Ensure the runtime user owns the cache directory in custom images.
Cache that directory between runs to keep installs fast.