Composer 1 is dead – Upgrade to Composer 2 now

Composer has long been the de-facto dependency manager for PHP projects. It powers millions of applications, frameworks, and libraries by providing a reliable way to manage dependencies. However, Composer 1 reached its end of life and is no longer maintained. If your project or CI pipeline is still using Composer 1, it’s time to upgrade.

What happens if your project still requires Composer 1?

If your composer.json specifies a constraint like ^1 for the Composer runtime, your build on Upsun or Platform.sh will fail.
Here’s the kind of error you’ll see:

      Building application 'app' (runtime type: php:8.3, tree: 7760752)
        Generating runtime configuration.

        Installing build dependencies...
          Installing php build dependencies: composer
          W: Changed current directory to /app/.global/composer
          W: No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.
          W: Loading composer repositories with package information
          W: Updating dependencies
          W: Your requirements could not be resolved to an installable set of packages.
          W:
          W:   Problem 1
          W:     - Root composer.json requires composer ^1, found composer[2.8.11] but it does not match the constraint.

How to check your Composer version

To check your current Composer version, execute the following:

composer --version

If you see Composer version 1.x.x, you are running the deprecated version.

How to upgrade your project to Composer 2

Upgrading is straightforward:

1. Update globally (recommended)

If Composer is installed globally on your system:

composer self-update --2

This will switch you directly to the latest stable Composer 2 release.

2. Install via Package Manager

For example, on macOS with Homebrew:

brew update
brew upgrade composer

3. Use the official installer

If you installed Composer manually:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --2
php -r "unlink('composer-setup.php');"

This will download Composer 2 locally into your project. You can move it globally if needed:

mv composer.phar /usr/local/bin/composer

Actions to take in your project

using Upsun
using Platform.sh

Update your composer.json Update the required PHP version and add a runtime API requirement to enforce Composer 2:
{ "require": { "php": ">=8.2", "composer-runtime-api": "^2" } }
Your current PHP version is maybe outdated?
Composer 2 requires at least PHP 7.2.5, but many modern packages no longer support versions below PHP 8.1. To ensure long-term compatibility, security, and access to the latest ecosystem improvements, we strongly recommend upgrading to PHP 8.2 or higher.
Check your .upsun/config.yaml Ensure you declare Composer 2 in your .upsun/config.yaml configuration, or, as Composer version 2 is now the default version installed on every project, completely remove the Composer dependency:
applications: app: dependencies: php: composer: "^2" # or remove this dependency as Composer v2 is the default
Test dependency resolution Run composer update with Composer 2 and commit the updated composer.lock. In rare cases, some legacy packages may need adjustments:
composer update git add .upsun/config.yaml composer.lock git commit "Update Composer to version 2" upsun push
Update your CI/CD pipelines
Check your Docker images, GitHub Actions, or other CI jobs. Many older PHP images still ship with Composer 1 by default.
- For Docker, use the composer:2 official image.
- For GitHub Actions, specify a step to upgrade Composer.
Communicate the change
Update your project’s documentation to state that Composer 2 is required.

Update your composer.json Update the required PHP version and add a runtime API requirement to enforce Composer 2:
{ "require": { "php": ">=8.2", "composer-runtime-api": "^2" } }
Your current PHP version is maybe outdated?
Composer 2 requires at least PHP 7.2.5, but many modern packages no longer support versions below PHP 8.1. To ensure long-term compatibility, security, and access to the latest ecosystem improvements, we strongly recommend upgrading to PHP 8.2 or higher.
Check your .platform.app.yaml Ensure you declare Composer 2 in your .platform.app.yaml (or .platform/applications.yaml) configuration, or, as Composer version 2 is now the default version installed on every project, completely remove the Composer dependency:
name: app dependencies: php: composer: "^2" # or remove this dependency as Composer v2 is the default

Test dependency resolution Run composer update with Composer 2 and commit the updated composer.lock. In rare cases, some legacy packages may need adjustments:

composer update
git add .platform.app.yaml .platform/applications.yaml composer.lock 
git commit "Update Composer to version 2"
platform push

Update your CI/CD pipelines
Check your Docker images, GitHub Actions, or other CI jobs. Many older PHP images still ship with Composer 1 by default.
- For Docker, use the composer:2 official image.
- For GitHub Actions, specify a step to upgrade Composer.
Communicate the change
Update your project’s documentation to state that Composer 2 is required.

Troubleshooting common migration issues

Upgrading from Composer 1 to 2 is usually seamless, but you may encounter issues:

API Rate Limits (GitHub, GitLab, etc.)
Composer 2 uses parallel downloads which can trigger API rate limits. Solution: configure OAuth tokens for GitHub or GitLab in your auth.json.
Plugins Not Compatible
Some Composer plugins written for v1 may not work on v2. Ensure you update plugins to their latest version, or replace them if no update is available.
Stricter Dependency Checks
Composer 2 is stricter about dependency resolution. If you encounter errors, check your composer.json for constraints that need adjusting.
CI/CD Caching Issues
Clear your Composer cache in CI/CD environments (composer clear-cache) if builds fail after upgrading.

Conclusion

Composer 1 is officially unsupported. By upgrading to Composer 2, you get:

Faster dependency resolution
Modern PHP compatibility
A safer, future-proof environment

Don’t wait until a dependency breaks or your pipeline fails—upgrade today.

​What happens if your project still requires Composer 1?

​How to check your Composer version

​How to upgrade your project to Composer 2

​1. Update globally (recommended)

​2. Install via Package Manager

​3. Use the official installer

​Actions to take in your project

​Troubleshooting common migration issues

​Conclusion

What happens if your project still requires Composer 1?

How to check your Composer version

How to upgrade your project to Composer 2

1. Update globally (recommended)

2. Install via Package Manager

3. Use the official installer

Actions to take in your project

Troubleshooting common migration issues

Conclusion