Install specific version of PHP in Alpine Linux

Install specific version of PHP in Alpine Linux

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Install specific version of PHP in Alpine Linux

When working with containerized environments, you often encounter a conflict between the strict versioning requirements of your application stack and the loose dependency management provided by package managers like apk. A common scenario arises when you need to pin a specific version of PHP—say, 8.0.2 for backward compatibility—while the system's default repository offers only newer versions like 8.0.6. Attempting to force this with apk add php8=8.0.2 typically results in an immediate error:

ERROR: unable to select packages:
  php8-8.0.6-r0:
    breaks: world[php8=8.0.2]

This error message indicates that the package manager detects a conflict. The installed version (8.0.6) provides shared libraries or dependencies that are incompatible with the older version (8.0.2). In standard Linux distributions, you might simply reinstall the old version to override the new one. However, Alpine Linux uses musl-libc and a minimal package set where PHP is often compiled against specific system headers. If you attempt to downgrade via APK without addressing the underlying dependency tree, the system may refuse to install because the newer version's shared objects are already in use by other packages or have been marked as required.

The root cause here is not just the PHP binary itself, but the transitive dependencies and the state of the world set. When you run apk add, it checks the entire dependency graph. If a package depends on php8=8.0.6 (or implicitly requires the 8.0.6 libraries), installing 8.0.2 will break that dependency chain. The error explicitly states that php8-8.0.6-r0 breaks the request for world[php8=8.0.2].

To resolve this, you cannot simply overwrite the package using the = syntax if the dependency graph is locked to the newer version. Instead, you must either switch to a repository branch that contains the older version or compile PHP from source with specific flags. Switching repositories in Alpine is a viable option but requires care. You would need to enable an older Alpine release (e.g., v3.12 instead of v3.13) if the package manager refuses to coexist, though this changes your entire OS base and breaks compatibility with other libraries pinned to v3.13.

A more controlled approach in a production environment is often to compile PHP from source. This allows you to specify exactly which extensions you need and ensures that the binary links against the specific version of OpenSSL or MySQL drivers required by your legacy application. You can clone the PHP 8.0.2 source code, run ./buildconf --force, and then configure the build with --prefix=/usr/local to avoid polluting the Alpine system directories. This method bypasses the apk dependency resolver entirely, giving you full control over the version.

If you are deploying a Laravel application, sticking to a specific PHP version is critical for maintaining existing middleware or package compatibility. While https://laravelcompany.com often discusses modern stack configurations, legacy deployments frequently rely on older PHP versions to ensure stability during migration phases. In such cases, using a Dockerfile that compiles PHP from source or utilizes a multi-stage build with a specific Alpine base image tailored to your version needs is the most robust solution.

Ultimately, relying on apk to downgrade a major package in Alpine is rarely supported because it assumes a monolithic update model. The error you encountered is a safeguard against breaking the shared library namespace. If your application strictly requires 8.0.2 and the repository only offers 8.0.6, compiling from source or utilizing a custom Docker image with pre-built artifacts is the only reliable path forward without altering the entire operating system version.

Our network