Include WP-CLI in all WordPress images

For a while now, WP-CLI has become the official way to manage WordPress from scripts / command line.

But if you glance through docker-entrypoint.sh, the current way of installing WordPress and hacking wp-config.php with sed and awk is not pretty and error-prone compared to a bunch of WP-CLI commands like

wp core download
wp config set
wp core install

WP-CLI doesn't take too much space, and it's become essential. I propose to:

include WP-CLI in all official WordPress images,
deprecate the stand-alone WP-CLI image,
refactor docker-entrypoint.sh using WP-CLI.

It will show the community the relevant way of managing WordPress from the command line, and will make it easier to actually use the image later on. It will also solve #256.

Having the same problem. It would be nice to be included in WP image.

While it is a great tool, it is not included in the image for a number of reasons:

it is not the canonical way to install wordpress (https://codex.wordpress.org/Installing_WordPress)
it cannot be removed; some users won't need it

the cli image can be used to manage a wp installation in another container

$ docker run --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:5.7
2bc33cf6d0f63ddd04ab46af874aac441377d9878ed3de303354e6a53ce82a2f
$ docker run --name some-wordpress --link some-mysql:mysql -p 8080:80 -d -e WORDPRESS_DB_PASSWORD=my-secret-pw wordpress
dc783a30d5a4e546e74f0b9c3a04312c1b7d107208dd0fc97aea1770ee100454
$ docker run -it --rm \
>     --volumes-from some-wordpress \
>     --network container:some-wordpress \
>     wordpress:cli user list
Error: The site you have requested is not installed.
Run `wp core install` to create database tables.
$ # ran through setup in browser
$ docker run -it --rm     --volumes-from some-wordpress     --network container:some-wordpress     wordpress:cli user list
+----+------------+--------------+-----------------+---------------------+---------------+
| ID | user_login | display_name | user_email      | user_registered     | roles         |
+----+------------+--------------+-----------------+---------------------+---------------+
| 1  | asdf       | asdf         | abc@example.com | 2018-06-22 21:42:02 | administrator |
+----+------------+--------------+-----------------+---------------------+---------------+

1. https://codex.wordpress.org/Installing_WordPress DOES contain the suggestion to use wp-cli:

Installing through wp-cli wp-cli is a great command line tool with which you can easily install and update WordPress and themes and extensions.

2. Most users need it (those kind of users who mess with Docker, most of them), and it’s tiny so it doesn’t really matter. 3. WP-CLI can be used from WordPress image or anyone can craft a their own WP-CLI-only image if they desire so. The fact that WP-CLI and WP images are based on different distribution is troublesome as linked issues show. Including WP-CLI will make wp so much more programmatically manageable.

Personally, I use it for managing users, roles, and plugin activation/dectivation from CLI. I agree that:

It's a small utility in comparison to WP.
Having to deploy a separate container just for this - by me it's an overkill.
As part as WP containers build and automation I don't like the idea that to activate plugins (from CLI) - I need to run another container ... just because the wp-cli is missing

Yes, I also found it very useful! And I think that is lightweight and really is not intrusive for people that not use it.

Any updates on this? Are there any plans to include wp-cli in WordPress docker images?

I too am interested to see. Currently using a variant just to get CLI running. Feels like this should be baked in.

I also agree. I feel like anyone who's using Docker to manage WordPress installations is very, very likely to use CLI too.

I also anticipated this being built in. Considering the barrier to entry is understanding and using Docker, WP CLI would be a justifiable inclusion for devops workflows.

Are there news on this? It would really be a good choice to do it!

An issue with relying on the current wordpress:cli image for this functionality is that, as explained here, the CLI image is based on Alpine whereas the WordPress Apache images are based on Debian, resulting in differing uid's, preventing the CLI from doing basic things like downloading & installing a new plugin.

A possible solution to this would be to use one of the Alpine WordPress images, but apparently using one of these would require you also spin up a separate Apache container, which I expect most people aren't interested in doing.

There shouldn't be anything stopping the CLI image from running as an arbitrary user, ala docker run ... --user 33:33 wordpress:cli wp ... (https://github.com/docker-library/docs/tree/master/wordpress#running-as-an-arbitrary-user).

@tianon

@tianon Yeah, turned out to be a different issue. Thanks.

I have created some images which include wp-cli and some other nice stuff.
Currently only for php-fpm because I'm lazy to make the other ones (I will do it soon ).
https://github.com/ivandotv/docker-wordpress-image

But if you have wp-cli in each wordpress instance, you have to do the same (change your command)?

But if you have wp-cli in each wordpress instance, you have to do the same (change your command)?

No you don't. That's the big advantage.
When wp-cli is bundled with Wordpress, wp-cli will use the default path, which corresponds to the current WordPress instance.

If you're using docker-compose, you can just run the following command:

docker-compose exec my_wordpress_with_cli wp user list

And just replace the my_wordpress_with_cli with the name of the WP instance you want to manage.

So you have a lot of wordpress sites in one docker-compose.yaml file if i understand that correctly?
Are you using named volumes or host binding?

So you have a lot of wordpress sites in one docker-compose.yaml file if i understand that correctly?

Well, that's not my use case, I usually only have one WordPress at the time, but this is the use case for the point you mentioned.

Are you using named volumes or host binding?

Why this would be relevant ?

@madmath03

@madmath03
With this command you can still connect to all stacks if you have consistent naming, just change $NAME

NAME=wpdev && docker run -it \
--volumes-from="${NAME}_wordpress_1" \
--network="${NAME}_default" \
wordpress:cli-php7.4 \
\
/bin/bash -c "wp core update"
Success: WordPress is up to date.

Or if you have non-consistent naming place .env file in your docker-compose.yaml folder, docker-compose will read it automatically:

---------- 420 buk 345233  236 Jan 26 14:06 .env
---------- 420 buk 345233  124 Jan 26 14:06 docker-compose.yaml

# .env
NETWORK_NAME=mynetwork
WORDPRESS_CONTAINER=mycontainer

# docker-compose.yaml
networks:
  test:
    name: $NETWORK_NAME

services:

  wordpress:
    container_name: $WORDPRESS_CONTAINER
    networks:
      - test

  mysql:
    networks:
      - test

And then run:

source .env && \
docker run -it \
--volumes-from="${WORDPRESS_CONTAINER}" \
--network="${NETWORK_NAME}" \
wordpress:cli-php7.4 \
\
/bin/bash -c "wp core update"
Success: WordPress is up to date.

To use name in networks you have to use docker-compose >= 3.4
Also, keep in mind:

Values in the shell take precedence over those specified in the .env file. If you set TAG to a different value in your shell, the substitution in image uses that instead

See https://docs.docker.com/v17.12/compose/environment-variables/#set-environment-variables-with-docker-compose-run

Or use labels :)

@madmath03

@madmath03

It's as you mentioned before: the cli image can be used to manage a wp installation in another container.

This is not a viable solution and the community has told you this in multiple different ways. The wp-cli is the only SANE way to manage wordpress in a Docker environment, period.

Well, that's not my use case, I usually only have one WordPress at the time, but this is the use case for the point you mentioned.

Your use case is irrelevant.

And just replace the my_wordpress_with_cli with the name of the WP instance you want to manage.

Also not effective. Not everyone has docker-compose installed, or even uses Docker with OCI containers to begin with. This is a hack, and not a good one at that.

People are repeatedly telling you that the "other container solution" is not effective, doesn't fit the general use case of wordpress in a standalone container, and that wp-cli is not optional or arbitrary. Furthermore the excuses for why it's not included are absolutely nonsensical - if you're that concerned about the size of the container, make a "minimal" tag that doesn't include it, which is actually the idiom that many containers use in the first place.

@madmath03

@madmath03

Yet another reason why your second container hack isn't viable, straight from the documentation itself:

NOTE: Since March 2021, WordPress images use a customized wp-config.php that pulls the values directly from the environment variables defined above (see wp-config-docker.php in docker-library/wordpress#572 and docker-library/wordpress#577). As a result of reading environment variables directly, the cli container also needs the same set of environment variables to properly evaluate wp-config.php.

Please keep the discussion respectful.

could not we just post here a dockerfile, which is FROM wordpress and adds a CLI installation to the image, then using that?

There is also problem we did not mentioned here before when running cli from other container.

In the old days for the cli it was enough to know the path for the wp installation folder, so multiple wp installations could be handled by simply using the default path or the --path switch of the cli. So we may think that using docker volumes creatively and allowing the necessary network connectivity we can still use one cli container for multiple wp docker containers.

However there is a trap, which makes this thing more painfully what it seems:

The newer wp docker images do not write the db info and credentials to wp-config.php, instead just write environment variable references to the wp-config.php. This means, that cli can not get that information by simply reading the pointed wp folders wp-config.php. If the cli is running in other container, it is impossible for it to get the values those env variables. The only way is, to set the same env variables redundantly in the cli container too. So we must manage multiple sets of environment variables and spin up the cli image every time with different set of the environment variables, because pointing to a wp installation folder is not enough anymore

This is also now a big issue with Docker-based management systems like Coolify. I finally figured out a way to get the WP-CLI container to talk to my WP container, but then I'll need to do all those steps for my other sites.

But even then, I have to enter or exec the WP-CLI container specific to that site in order to do things with the other container.

It would be so much easier, faster, and simpler to package them together (or simply offer a third image like wordpress:with-cli) so WP-CLI can be run within the container it's actually controlling.

This issue is almost 7 years old. 😢

This is one more way of using WP, WPCLI in one image https://github.com/wodby/wordpress-php?tab=readme-ov-file works like charm.
docker pull wodby/wordpress-php:8.3

New to this docker image and was surprised to find CLI wasn't included in the standard image.
Given the UID conflicts (#256), seems like a logical way to properly solve both issues; include it in the base image.

That, or having a quick and easy "this is how you add it to a custom image" sample dockerfile that we can use.

If WP-CLI wasn't the "official command line tool" then I'd agree, separate image.

www-data

The only other consideration would be that include wp-cli in the base image would mean it would be running as root by default, which makes using it cumbersome.

Perhaps an alias could be set up for wp in that container so it auto uses www-data? (Though su won't like the /nologin bash on that account... Second user?)
Or use Sudo, plus preserve env to pass through env variables:

sudo --preserve-env -u www-data /bin/wp-cli.phar $*

cli doesn't get env vars from wordpress image #594 (comment)

Navigation Menu

Repository navigation

Include WP-CLI in all WordPress images #283

8 remaining items

www-data

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Include WP-CLI in all WordPress images #283

Description

Activity

ConstantinElse commented on Jun 22, 2018

yosifkit commented on Jun 22, 2018

mvasin commented on Jun 23, 2018

ConstantinElse commented on Jun 23, 2018

barcia commented on Sep 23, 2018

aseempatni commented on Oct 5, 2018

alexstandiford commented on Oct 29, 2018

davilera commented on Dec 14, 2018

darrenbarklie commented on Dec 15, 2018

ffranchina commented on Mar 9, 2019

narthur commented on Jul 23, 2019

tianon commented on Jul 23, 2019

narthur commented on Jul 24, 2019

ivandotv commented on Jan 21, 2020

8 remaining items

bukowa commented on Jan 26, 2020

madmath03 commented on Jan 26, 2020

bukowa commented on Jan 26, 2020

madmath03 commented on Jan 26, 2020

bukowa commented on Jan 26, 2020

weeping-somnambulist commented on Feb 27, 2023

weeping-somnambulist commented on Feb 27, 2023

tianon commented on Mar 3, 2023

pievalentin commented on Apr 24, 2023

pluraltouch commented on Jan 25, 2024

pluraltouch commented on Jan 25, 2024

audioscavenger commented on Mar 24, 2024

theDanielJLewis commented on Oct 24, 2024

sandykadam commented on Feb 14, 2025

XVII commented on Sep 10, 2025

www-data

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions