19.2.2.4 Ps Format Option

The format option in docker ps allows customizing the output to display exactly the fields needed in the desired layout. By default, docker ps prints a fixed set of columns in a human-readable table. The --format flag replaces this default output with a template, enabling tailored displays for dashboards, scripts, log parsers, or any use case where the default table is too wide, missing a field, or returns more information than needed.

Basic Syntax

docker ps --format "TEMPLATE"

The template uses Go's text/template syntax. Container fields are accessed with double curly braces and a dot prefix:

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

Available Template Fields

Printing a Single Field

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

web-server
database
cache

docker ps --format "{{.ID}}"

a1b2c3d4e5f6
b2c3d4e5f6a7
c3d4e5f6a7b8

Combining Multiple Fields

Fields can be concatenated with separators:

docker ps --format "{{.Names}}: {{.Status}}"

web-server: Up 3 hours
database: Up 3 hours
cache: Up 1 hour

Using tab separators:

docker ps --format "{{.ID}}\t{{.Names}}\t{{.Status}}"

a1b2c3d4e5f6    web-server    Up 3 hours
b2c3d4e5f6a7    database      Up 3 hours

The table Directive

Prefixing the template with table adds column headers and aligns values into a readable table:

docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

NAMES        IMAGE          STATUS
web-server   nginx:latest   Up 3 hours
database     postgres:15    Up 3 hours
cache        redis:7        Up 1 hour

The header row is generated automatically by capitalizing the field name. Without the table directive, no header is printed, which is suitable for scripts that process each line.

JSON Output Per Line

docker ps --format "{{json .}}"

Each container produces one line of JSON:

{"Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","CreatedAt":"2024-06-15 10:00:00 +0000 UTC","ID":"a1b2c3d4e5f6","Image":"nginx:latest","Labels":"","LocalVolumes":"0","Mounts":"","Names":"web-server","Networks":"bridge","Ports":"0.0.0.0:8080->80/tcp","RunningFor":"3 hours ago","Size":"0B (virtual 142MB)","Status":"Up 3 hours"}

This output can be piped into jq for querying:

docker ps --format "{{json .}}" | jq '.Names + " → " + .Status'

"web-server → Up 3 hours"
"database → Up 3 hours"

Accessing Specific Labels

To display the value of a container label, use the .Label function with the label key:

docker ps --format "{{.Names}}\t{{.Label \"env\"}}"

web-server    production
database      production

If the label does not exist on a container, an empty string is printed for that container.

Template Conditionals

Go templates support if blocks for conditional output:

docker ps --format "{{.Names}}: {{if eq .Status \"Up\"}}RUNNING{{else}}STOPPED{{end}}"

This is useful for status indicators where a simple string comparison determines what to display.

Persisting a Custom Format

Running docker ps with a long format string repeatedly is inconvenient. The format can be set as the default in Docker's client configuration file at ~/.docker/config.json:

{
  "psFormat": "table {{.Names}}\\t{{.Image}}\\t{{.Status}}\\t{{.Ports}}"
}

With this set, running docker ps without any --format flag uses the configured template automatically.

Practical Format Examples

Status summary for monitoring

docker ps --format "{{.Names}} [{{.Status}}]"

Show image and uptime side by side

docker ps --format "table {{.Names}}\t{{.Image}}\t{{.RunningFor}}"

Export container information to CSV

echo "ID,Name,Image,Status" > containers.csv
docker ps --format "{{.ID}},{{.Names}},{{.Image}},{{.Status}}" >> containers.csv

Show containers with their networks

docker ps --format "table {{.Names}}\t{{.Networks}}\t{{.Ports}}"

Identify containers with no published ports

docker ps --format "{{.Names}}\t{{.Ports}}" | grep -v "->"

(Lines with no -> have no published ports.)