/compare/composer/composer-install-vs-composer-update
composer install vs composer update: differences and when to use each
- tool
- Composer
- compares
- composer install vs composer update
composer install installs exactly the versions recorded in composer.lock, so every machine gets the same code; it only resolves dependencies itself when no lock file exists. composer update ignores the locked versions, resolves the constraints in composer.json again, installs the newest versions they allow and rewrites composer.lock. Run install in CI, Docker builds and after cloning; run update (ideally for named packages) when you want to upgrade.
Side by side
| Criterion | composer install | composer update |
|---|---|---|
| Reads | composer.lock (composer.json only if no lock) | composer.json |
| Writes composer.lock | Only when it did not exist | Always |
| Changes versions | No | Yes, within the constraints |
| Same result on every machine | Yes | No: depends on when it runs |
| Scope | Whole project | Whole project, or named packages (composer update vendor/pkg) |
| Speed | Faster: no dependency resolution | Slower: runs the solver |
| Typical use | CI, deployments, fresh clones | Upgrading dependencies, after editing composer.json |
Commands
composer install # reproducible install from composer.lock
composer install --no-dev --optimize-autoloader # production deployment
composer update vendor/package # upgrade one package (and keep the rest)
composer update vendor/package -W # also let its dependencies move
composer update --dry-run # show what would change
composer outdated --direct # list direct dependencies with newer releasesCommit composer.lock for applications. For libraries the lock file is not used by projects that depend on them; many libraries still commit it so their own CI is reproducible.
Which one to use
- Fresh clone, CI, Docker image, deployment:
composer install, with--no-dev --optimize-autoloaderfor production. It never changes versions, so what was tested is what ships. - Adding a package:
composer require vendor/pkg, which editscomposer.jsonand updates only what the new package needs. - Upgrading one package:
composer update vendor/pkg, adding-wor-Wwhen its dependencies must move too. - Routine upgrades:
composer outdated --directto see what is behind, then update a few packages at a time and run the tests. - After editing composer.json by hand:
composer updatefor the packages whose constraints you changed; otherwisecomposer installwarns that the lock file is not up to date.
Update options
| Option | Effect |
|---|---|
| composer update vendor/pkg | Update only that package; its dependencies stay locked when possible |
| -w, --with-dependencies | Also allow its dependencies to update, except those that are root requirements |
| -W, --with-all-dependencies | Also allow all its dependencies to update, including root requirements |
| --lock | Only refresh the lock file hash and metadata; no versions change |
| --dry-run | Print the operations without changing anything |
| --prefer-lowest | Install the lowest allowed versions; libraries use it in CI to test their minimum constraints |
When an update cannot satisfy every constraint, Composer stops with Your requirements could not be resolved to an installable set of packages and lists the conflicting requirements; the lock file and vendor/ stay as they were.
FAQ
Why does composer install say the lock file is not up to date?
composer.json was edited after composer.lock was written, so the lock no longer matches it. Run composer update for the packages you changed (or composer update --lock if only metadata changed) and commit the new lock file.
Does composer require run update?
Yes, for the package you add: composer require vendor/pkg edits composer.json and updates that package and what it needs in composer.lock, leaving other locked versions alone.
Is it safe to delete composer.lock and run composer update?
Only if you are ready for every dependency to move to the newest allowed version at once. It is the largest possible upgrade; updating named packages is easier to review and test.