Introduction

If you want to stop Docker containers by image name, you first need to identify which running containers were created from that image and then pass their container IDs to docker stop. On Ubuntu, the shell makes this easy with Docker's filtering options plus standard command-line piping.

Find containers by image ancestry

Docker can filter running containers using the ancestor filter, which matches containers created from a given image.

docker ps --filter "ancestor=nginx"

That shows all running containers based on the nginx image. To return only their container IDs, use -q.

docker ps -q --filter "ancestor=nginx"

Those IDs are what docker stop needs.

Stop them directly

The shortest pattern is:

docker ps -q --filter "ancestor=nginx" | xargs -r docker stop

This does three things:

• lists matching running container IDs
• passes those IDs to xargs
• calls docker stop on each one

The -r flag on Ubuntu's xargs avoids running docker stop when there are no matching containers.

Example with a specific tag

If you need to target a tagged image exactly, include the tag.

docker ps -q --filter "ancestor=myapp:1.2.0" | xargs -r docker stop

This is safer than matching only the repository name when multiple versions may be running.

Preview before stopping anything

If you are operating on production or shared development machines, preview the matches first.

docker ps --filter "ancestor=myapp:1.2.0" --format "table {{.ID}}\t{{.Image}}\t{{.Names}}"

That gives you a human-readable confirmation before you stop anything.

A reusable shell function

If you do this often, a small shell function is clearer than copying pipelines repeatedly.

1stop_by_image() {
2  local image="$1"
3  docker ps -q --filter "ancestor=$image" | xargs -r docker stop
4}
5
6stop_by_image nginx

This is easier to remember and reduces quoting mistakes.

Compose projects are different

If those containers were started by Docker Compose, it is often better to manage them through Compose itself.

docker compose stop

Compose understands the project as a unit, while image-based stopping only looks at ancestry.

Be explicit about what you match

When several repositories share a common base image, stopping by image ancestry can affect more containers than expected. A quick preview with docker ps --filter "ancestor=..." is the safest "dry run" before you stop anything on a shared machine.

Force versus graceful stop

docker stop sends a termination signal and then waits before killing the process if it does not exit. That is usually what you want. If you use docker kill instead, containers do not get the same chance to shut down cleanly.

That distinction matters for databases, queues, and other stateful services.

If you need a different grace period, Docker lets you set one explicitly. That can help when containers need a few extra seconds to flush logs or finish in-flight work.

docker stop --time 20 $(docker ps -q --filter "ancestor=myapp:1.2.0")

Common Pitfalls

A common mistake is filtering by a partial image name and accidentally matching more containers than intended. Tags matter when several image versions coexist.

Another issue is forgetting that ancestor matches containers created from that image, not arbitrary metadata you may have attached later.

It is also easy to use xargs without -r and get noisy or confusing behavior when no matching containers are running.

Summary

• Use docker ps --filter "ancestor=..." to find containers created from a given image.
• Add -q to get only container IDs.
• Pipe the IDs into xargs -r docker stop to stop them cleanly on Ubuntu.
• Preview the matches first when accuracy matters.
• Prefer docker compose stop when the containers are part of a Compose-managed application.