PHP error guide
Composer dist download failed: meaning and fix
Error summary
Install ext-zip or a trusted unzip implementation, or permit source fallback with VCS available. Composer cannot unpack the distribution archive with available PHP or system tools.
What it means
Install ext-zip or a trusted unzip implementation, or permit source fallback with VCS available. Composer cannot unpack the distribution archive with available PHP or system tools.
What the error means
This message means that Composer cannot unpack the distribution archive with available PHP or system tools. The exact signature distinguishes composer dist download failed from a generic application failure.
Why PHP produces it
The engine or service reports “Composer dist download failed” because its required precondition was not met. Install ext-zip or a trusted unzip implementation, or permit source fallback with VCS available.
PHP version notes
The composer dist download failed wording here is based on Composer 2.x; punctuation and exception class names can differ on older branches or vendor builds.
Most common causes
- The immediate input or configuration reaches the specific condition: Composer cannot unpack the distribution archive with available PHP or system tools
- The code path assumes the prerequisite for composer dist download failed has already been satisfied.
- For composer dist download failed, development and production differ in version, extension, permissions, paths, or service configuration.
- An earlier operation returned an unchecked value that is consumed by the line reporting composer dist download failed.
Minimal examples
BAD — reproduces the problem
composer install --prefer-dist
FIXED — safer pattern
php -m | grep zip
composer install --prefer-dist -vvv
Step-by-step diagnosis
- Copy the complete “Failed to download acme/package from dist: The zip extension and unzip/7z commands are both missing, skipping.” text and retain the first application stack frame.
- Reproduce composer dist download failed in the same SAPI and environment listed for this page.
- Before changing composer dist download failed, inspect the preceding value or directive and verify its type, path, version, and permissions.
- Apply the narrow correction—install ext-zip or a trusted unzip implementation, or permit source fallback with VCS available—then repeat the original request once.
Fixes
Correct the failing prerequisite
Install ext-zip or a trusted unzip implementation, or permit source fallback with VCS available
php -m | grep zip
composer install --prefer-dist -vvv
Fail explicitly at the boundary
Validate the condition before the operation that emits composer dist download failed, and log a safe diagnostic without credentials or full production paths.
Common mistakes when fixing it
- Suppressing composer dist download failed instead of correcting its upstream condition.
- Testing composer dist download failed only with the CLI binary when the failing request runs under FPM or Apache.
- Changing a global setting for composer dist download failed before confirming the site-specific effective configuration.
How to prevent it
- Add a focused test that exercises the boundary responsible for composer dist download failed.
- Keep runtime versions, extensions, configuration, and deploy artifacts affecting composer dist download failed reproducible.
- Validate external data and service return values before they can trigger composer dist download failed.
Web server / environment notes
cli, composer, linux, docker. The failure occurs where composer cannot unpack the distribution archive with available PHP or system tools
Tags: cli,composer,linux,docker