Docker Community Forums

Share and learn in the Docker community.

What filters are available for `docker-compose ps`?

The docker-compose ps doc does not say what filters we can use. The docker ps doc says docker ps supports the health filter, but evidently docker-compose ps does not:

$ docker-compose ps --service --filter "health=healthy"
ERROR: Invalid filter: health

Where do we find what filters are available?

Ultimately, I’d like docker-compose up --detach to wait for all containers to finish starting up before docker-compose exits so I know that it has happened without having to docker ps and look manually over and over.

According to the help page, you can filter by presumably any container property.

$ docker-compose help ps
 List containers.

 Usage: ps [options] [SERVICE...]

 Options:
 -q, --quiet          Only display IDs
 --services           Display services
 --filter KEY=VAL     Filter services by a property

I keep running into this question in Google search results and it still doesn’t have an answer. I decided to do something about that.

For compose v1 the source code tells me that ‘status’ and ‘source’ are valid filter keys (status=??? or source=???), with status being allowed to take values ‘running’, ‘stopped’, ‘paused’ or ‘restarting’ and source being allowed to take values ‘image’ or ‘build’.

This would suggest the following is an exhaustive list of all single-filter filter values:

  • status=running
  • status=stopped
  • status=paused
  • status=restarting
  • source=image
  • source=build

As an aside, services that are restarting will be listed when running docker-compose ps --services filter "status=running" so the whole filter thing is a bit squiffy.

compose v2 removes the ‘filter’ option and so over time this question will disappear into irrelevance.

1 Like