Introduction

The default docker ps table is useful for people, but scripts usually need one field at a time. If you only need running container names, Docker formatting options give predictable output that is safe for automation. Using explicit formats also reduces fragile parsing code and production mistakes.

List Only Running Container Names

The primary command is:

docker ps --format '{{.Names}}'

This prints one container name per line for running containers only. If you also need stopped containers, add -a.

docker ps -a --format '{{.Names}}'

For scripts, this format is better than parsing columns from the default table output.

Add Filters Before Formatting

Filters narrow scope before output formatting, which is safer than filtering later with broad text matching.

1# Only containers with a label
2docker ps --filter label=service=api --format '{{.Names}}'
3
4# Only unhealthy running containers
5docker ps --filter health=unhealthy --format '{{.Names}}'
6
7# Name prefix match via filter and grep
8docker ps --format '{{.Names}}' | grep '^api-'

Filtering early reduces accidental operations on unrelated containers.

Use Names in Automation Pipelines

Name-only output is ideal for shell pipelines.

1# Restart matching running containers safely
2docker ps --format '{{.Names}}' | grep '^worker-' | xargs -r docker restart
3
4# Stop all running containers by name
5docker ps --format '{{.Names}}' | xargs -r docker stop

Use xargs -r so no command runs when input is empty. This avoids noisy errors in CI jobs.

Structured Parsing with JSON Output

When scripts need multiple fields, emit JSON rows and parse with jq.

docker ps --format '{{json .}}' | jq -r '.Names'

You can pull name and status together:

docker ps --format '{{json .}}' | jq -r '"\(.Names) \(.Status)"'

Structured parsing is more stable than regex parsing of table output.

Reusable Shell Helpers

Teams benefit from shared helper functions for common operations.

1running_names() {
2  docker ps --format '{{.Names}}'
3}
4
5running_names_by_label() {
6  local label="$1"
7  docker ps --filter "label=$label" --format '{{.Names}}'
8}

Store helpers in a versioned script so everyone runs the same operational commands.

Debugging Unexpected Results

If command output is empty when containers are expected:

• Confirm containers are actually running.
• Check active Docker context.
• Verify name and label filters.
• Test with plain docker ps first.

docker context show
docker ps

Many empty-list issues come from using a different context than intended.

Security and Operational Notes

Container names may include environment or service identifiers. If command output is logged centrally, ensure this metadata is acceptable under your logging policy. In multi-tenant hosts, prefer label-based filtering over broad name patterns to avoid operating on containers owned by another stack.

For incident response scripts, print target names before destructive actions and require confirmation unless script is explicitly non-interactive.

Example Maintenance Script

The pattern below prints matching containers first, then restarts them. This reduces accidental operations during incident handling.

1#!/usr/bin/env bash
2set -euo pipefail
3
4targets=$(docker ps --filter label=service=api --format '{{.Names}}')
5printf 'Targets:\\n%s\\n' "$targets"
6
7if [ -n "$targets" ]; then
8  echo "$targets" | xargs -r docker restart
9fi

This script stays predictable because it relies on explicit Docker formatting rather than text-column parsing.

Common Pitfalls

• Parsing default docker ps tables with column positions that break over time.
• Forgetting -a when scripts expect stopped containers too.
• Running xargs without -r and triggering commands with empty input.
• Filtering late with broad grep patterns instead of Docker filters.
• Ignoring Docker context and querying the wrong daemon.

Summary

• Use docker ps --format '{{.Names}}' for clean name-only output.
• Combine filters with formatting for safer automation.
• Prefer JSON-formatted rows for multi-field script parsing.
• Wrap repeated commands in shared, versioned shell helpers.
• Validate Docker context and filters when results are unexpected.