When WordPress runs in Docker, PHP is part of the image the container runs. The dashboard updates WordPress and its plugins, but it has no way to change PHP. To get a newer PHP, you change the image: pull a rebuilt one, move to another tag, or rebuild your own.
This guide uses the official wordpress image and Docker Compose. The commands assume your WordPress service is called wordpress. Use your own service name if it isn't.
Back up first
Changing the image doesn't touch your volumes, so your uploads, plugins and database stay where they are. A plugin that breaks on the new PHP can still write bad data, though, so back up the database and wp-content before you switch.
1. See what you run now
docker compose images wordpress
docker compose exec wordpress php -v
The first command shows the image and tag the container was created from. The second shows the PHP inside it.
2. Read the tag
Official wordpress tags are made of up to three parts: a WordPress version, a PHP branch and a variant.
| Tag | WordPress | PHP | Variant |
|---|---|---|---|
wordpress:latest |
newest release | 8.3 | Apache |
wordpress:php8.4-fpm |
newest release | 8.4 | PHP-FPM |
wordpress:7.1-php8.5 |
newest 7.1.x | 8.5 | Apache |
wordpress:php8.4-fpm-alpine |
newest release | 8.4 | PHP-FPM on Alpine |
Two things catch people out. A tag with no PHP part, such as latest or 7.1, follows the image's default PHP branch, which is 8.3 today, not the newest PHP (generate-stackbrew-library.sh). And a tag with no variant is the Apache one.
The tag also decides whether PHP updates reach you at all. A tag that names a PHP branch, like php8.4-fpm, is rebuilt when PHP ships a release on that branch. A tag that names a full WordPress version, like 7.1.2-php8.3-fpm, stops being rebuilt once the next WordPress release is out. A digest (wordpress@sha256:...) never changes. Tags for end-of-life branches, such as php8.1-fpm, aren't rebuilt either.
3. Pick a PHP branch
PHP gives security fixes to four branches (supported versions):
| Branch | Security fixes until |
|---|---|
| 8.2 | 31 December 2026 |
| 8.3 | 31 December 2027 |
| 8.4 | 31 December 2028 |
| 8.5 | 31 December 2029 |
PHP 8.1 reached end of life on 31 December 2025 and gets no more releases (end-of-life branches). WordPress recommends PHP 8.3 or greater (requirements). If you're moving anyway, 8.4 gives you security fixes until the end of 2028.
The risk in a PHP upgrade sits in your plugins and theme more than in WordPress itself. Each branch removes or changes some functions, and older plugins are where that shows up first. Check that the plugins you rely on are still maintained, then test.
4. Try it on a copy
Run a copy of the site on the new tag before you touch production. The simplest copy is a second Compose project in another folder, with a copy of the database and of wp-content, and the new tag on its WordPress service. Open the pages that matter, log in to the dashboard, and watch the log:
docker compose logs -f wordpress
Deprecation notices tell you what will break on a later branch. Fatal errors mean a plugin or the theme needs an update before you switch.
5. Switch
Change the image: line of the WordPress service, for example from wordpress:php8.2-fpm to wordpress:php8.4-fpm. Then pull the image and recreate the container:
docker compose pull wordpress
docker compose up -d wordpress
up -d recreates the container from the new image and reattaches your volumes. If you run PHP-FPM behind nginx, the nginx container stays as it is. It has no PHP in it and talks to WordPress over FastCGI.
If you build your own image with FROM wordpress:..., change the FROM line and rebuild with --pull, so Docker fetches the new base instead of reusing one it already has:
docker compose build --pull wordpress
docker compose up -d wordpress
Extensions you add with docker-php-ext-install are compiled against the new PHP during the build. Extensions from PECL need a release that supports the new branch.
6. Check it worked
docker compose exec wordpress php -v
In the dashboard, Tools → Site Health → Info → Server shows the PHP version that serves your site. There are other ways too, covered in What PHP version is my WordPress site running?
Roll back
Put the old tag back on the image: line and recreate the container:
docker compose up -d wordpress
That undoes the PHP change. It doesn't undo database changes a plugin made while it ran on the new PHP. That's what the backup is for.
Keep it current
Pulling a newer image updates PHP, not your WordPress files. The official image copies WordPress into the volume only when it finds none there (docker-entrypoint.sh). After that, WordPress and plugin updates come from the dashboard, and PHP updates come from the image.
With a tag that names a PHP branch, PHP's patch releases reach you when you pull and recreate the container. Do that on a schedule, and again after every PHP security release. The rebuilt images don't appear at the moment PHP releases. On 21 October, PHP released the PHP2Shell fixes at about 13:37 UTC, and the rebuilt official wordpress images reached Docker Hub at about 17:50 UTC, four hours later. Run php -v after you pull to see which one you got.
With a pinned tag or a digest, someone has to change the pin every time. If your team has PHP pinned across many repositories, book 30 minutes with us.
To see whether the PHP you run now needs the PHP2Shell fix, paste your php -v output or your compose file into our free check.