Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

composer install says the lock file is not compatible and asks for update

ErrorYour lock file does not contain a compatible set of packages. Please run composer update.

Short answer

composer install checked the locked packages against this machine's PHP and extensions and found a conflict. The lines under the message name it. Fix the machine (right PHP, missing extension) or rebuild the lock for the PHP you deploy to. Running composer update blindly changes package versions.

  • Applies to Composer 2.8, PHP 8.3, Laravel 12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the problem lines printed under the message, then check the lock against the real platform of this machine.

    composer check-platform-reqs --lock
    php -v
  2. 2Match what you see, then jump to its fix

    1. 1The problem lines say a package requires php >= X or ext-something that this machine lacks.This PHP version or an extension does not satisfy a locked packageFix
    2. 2The lock was made on a developer laptop; the server has an older PHP and packages in the lock need the newer one.The lock file was built on a newer PHP than production runsFix
    3. 3Composer prints Warning: The lock file is not up to date with the latest changes in composer.json before the error.composer.json changed and the lock was not refreshedFix

What does the error look like?

  • Your lock file does not contain a compatible set of packages. Please run composer update.

Cause 1 of 3

This PHP version or an extension does not satisfy a locked package

1Check

On a plain install Composer solves the locked set again against this platform. If any locked package needs a newer PHP or an extension that is not loaded, the solve fails. The check-platform-reqs command reports the real platform, ignoring config.platform.

composer show --platform
composer check-platform-reqs --lock

2Fix

Run Composer under the PHP version the lock was made for, and install the missing extension. As a temporary measure only, ignore a named platform requirement for that single package set.

# temporary, for one requirement only
composer install --ignore-platform-req=ext-intl

3Verify

Install completes and the platform check is clean.

composer install
composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

Cause 2 of 3

The lock file was built on a newer PHP than production runs

1Check

composer update on a newer PHP can pick package versions the older PHP cannot run. The platform config exists to emulate the production environment while resolving.

grep -n -A3 '"platform"' composer.json

2Fix

Set the production PHP version as the platform, regenerate the lock, commit it, and install again on the server. The docs warn that faked platform values stop dependencies being checked on the machine itself, so run check-platform-reqs when you deploy.

// composer.json
"config": {
    "platform": { "php": "8.2.0" }
}

composer update

3Verify

A fresh install on the server works and the check passes.

composer install --no-dev && composer check-platform-reqs

Confirmed by getcomposer.org

Did this fix it?

Cause 3 of 3

composer.json changed and the lock was not refreshed

1Check

That warning alone does not stop an install; it tells you the lock and composer.json drifted apart, which is why the solve can disagree with the lock.

composer validate

2Fix

Update only what changed (a named package) so other versions stay put, or refresh the lock hash if nothing else needs to change.

composer update vendor/package
# or, hash only
composer update --lock

3Verify

The warning is gone.

composer validate

Confirmed by getcomposer.org

Did this fix it?

How do I stop it coming back?

  • Set config.platform.php to the production version before you ever run composer update.
  • Use the same PHP minor version in development, CI and production.
  • Commit composer.lock, and run composer validate in CI.
  • Prefer composer update vendor/package over a full update.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.