/commands/composer/composer-why-not
composer why-not vendor/package version: find what blocks an upgrade
- tool
- Composer
- versions
- Composer 2.x
- os
- any
composer why-not symfony/console 7.1 (alias composer prohibits) lists every installed package and root requirement that prevents symfony/console 7.1 from being installed, with the constraint each one sets. It is the first command to run when composer update refuses to move a package or composer require fails with a conflict. Its counterpart, composer why vendor/package (alias depends), lists what requires a package that is already installed.
Usage
composer why-not symfony/console 7.1 # what blocks version 7.1
composer why-not symfony/console 7.1 -r # recursive: follow the chain up to the root
composer why-not symfony/console 7.1 -t # as a nested tree (implies -r)
composer why-not php 8.4 # packages that do not allow PHP 8.4
composer why psr/log # which packages require psr/log
composer why psr/log -t # the full chain as a treeEach line of the output names a package, the relation (requires, conflicts) and the constraint that excludes the version you asked about.
Reading the answer
| What why-not shows | What to do |
|---|---|
| Your project requires symfony/console (^6.4) | Widen your own constraint: composer require symfony/console:^7.1 |
| vendor/a requires symfony/console (^5.4 || ^6.0) | Update vendor/a first, or wait for a release that supports 7.x |
| vendor/b conflicts with symfony/console (>=7.0) | A declared incompatibility; update or replace vendor/b |
| symfony/console 7.1 requires php (>=8.2) | Your PHP (or config.platform.php) is too old for that version |
| No output | Nothing installed blocks it: check the version exists and your minimum-stability |
Commands that fit together
composer outdated --directshows which direct dependencies have newer versions.composer why-not vendor/package VERSIONexplains why one of them does not move.composer update vendor/package -W, orcomposer require vendor/package:^NEW -W, performs the change once the blockers are resolved; see composer update one package.
Pitfalls
- Give a version.
why-notneeds the version (or constraint) you want; without it Composer cannot tell what to check. - Platform packages. Requirements on
phpandext-*come from your platform. A conflict there is fixed by upgrading PHP or installing the extension, not by changing packages; at run time it shows up as Composer detected issues in your platform. - Only installed packages are checked.
why-notlooks at what is installed and locked. A full resolution with new packages can still fail for other reasons; the solver output of Your requirements could not be resolved lists those.
How to confirm it worked
After removing a blocker, run composer why-not vendor/package VERSION again: no output means nothing installed prevents that version. Then run the update and check composer show vendor/package for the new version.
FAQ
What is the difference between composer why and composer why-not?
composer why vendor/package (alias of depends) lists the packages that require an installed package. composer why-not vendor/package version (alias of prohibits) lists what prevents that version from being installed.
Can why-not show PHP version problems?
Yes. Ask about the platform package, for example composer why-not php 8.4, to see which packages do not allow that PHP version, or check a package version whose php requirement your platform does not meet.
Why does why-not print nothing although the update does not happen?
Nothing installed conflicts with that version, so the limit is usually in your own composer.json constraint or the package version does not exist. Check composer show vendor/package --all for the available versions.