Composer install vs update: which one should I run and why does composer.lock matter?

composer install installs exactly the versions recorded in composer.lock. composer update ignores the lock file, resolves the newest versions allowed by the constraints in composer.json, installs them and rewrites composer.lock.

What to do

• On your machine: composer update vendor/package (or composer require) when you intentionally upgrade. Test. Commit both composer.json and composer.lock.
• On CI and servers: composer install. Everyone gets identical code, so a deploy cannot break because a dependency released a new version overnight.
• For production:

composer install --no-dev --optimize-autoloader --no-interaction

--no-dev skips PHPUnit and other dev tools. -o builds a class map for faster autoloading. Add --classmap-authoritative only if you never generate classes at runtime.

Version constraints in composer.json

• ^8.2 means >=8.2.0 <9.0.0 (caret allows non-breaking updates).
• ~8.2.1 means >=8.2.1 <8.3.0.
• * or dev-main is a risk; avoid in applications.

Libraries vs applications

Applications commit composer.lock. Libraries usually do not, because consumers resolve their own versions.

Common problems

• "Your lock file does not contain a compatible set of packages": the lock was made on a different PHP version. Set config.platform.php in composer.json to your production version so the resolver uses it.
• "The lock file is not up to date with composer.json": run composer update --lock (or composer update nothing) locally and commit.
• Security: composer audit lists known vulnerabilities in the locked packages.
• Out of memory during update: COMPOSER_MEMORY_LIMIT=-1 composer update.
• Never edit files inside vendor/. They are overwritten on the next install; patch with a fork or the cweagans patches plugin.