6 minute read

What lies behind us and what lies before us are tiny matters compared to what lies within us. - Ralph Waldo Emerson

Transform your Docker container management with powerful formatting tricks and Go template techniques

docker ps advanced formatting mastering-docker-ps-advanced-formatting

Mastering Docker PS: Advanced Formatting and Go Template Magic

Introduction

If you’ve been using Docker for a while, you’ve probably typed docker ps countless times. But did you know this simple command is hiding a treasure trove of advanced features that can transform how you view and manage your containers?

In this comprehensive guide, we’ll dive deep into Docker’s formatting capabilities, explore Go template syntax, and discover practical tricks that will make you a Docker command-line wizard.

The Problem with Default docker ps

Let’s be honest—the default docker ps output can be overwhelming:

  • Too many columns: Most of the time, you don’t need all the information
  • Truncated data: Important details get cut off
  • Poor readability: Information is hard to scan quickly
  • No customization: One size doesn’t fit all use cases

But what if I told you that docker ps can be completely customized to show exactly what you need, exactly how you want it?

Understanding Go Template Syntax

Docker uses Go’s powerful template engine for formatting output. Here’s the syntax breakdown:

Basic Structure

docker ps --format ""

The anatomy:

  • `` - Template delimiters
  • . - Refers to the current object (container)
  • FieldName - The property you want to display

Available Fields

Docker containers expose these template fields:

Field Description Example
`` Container ID a1b2c3d4e5f6
`` Container name my-web-app
`` Docker image nginx:latest
`` Current status Up 2 hours
`` Port mappings 0.0.0.0:80->80/tcp
`` Container command nginx -g daemon off;
`` Creation timestamp 2024-01-15 10:30:00
`` Running duration 2 hours ago
`` Container size 1.2MB
`` Container labels version=1.0
`` Volume mounts my-volume

Essential Formatting Techniques

1. Simple Custom Columns

Want just container names and status? Easy:

docker ps --format "table \t"

Output:

NAMES                STATUS
web-server           Up 2 hours
database             Up 2 hours (healthy)
redis-cache          Up 1 hour

2. Adding Table Headers

The table keyword automatically adds headers and proper alignment:

docker ps --format "table \t\t"

Why use table?

  • Automatic column headers
  • Proper text alignment
  • Professional appearance
  • Tab-separated columns

3. Custom Separators

Skip the table format for custom layouts:

docker ps --format " ->  ()"

Output:

web-server -> Up 2 hours (nginx:latest)
database -> Up 2 hours (postgres:13)
redis-cache -> Up 1 hour (redis:alpine)

Advanced Go Template Magic

Conditional Logic

Show different information based on container state:

docker ps --format ": No ports exposed"

Template breakdown:

  • `` - Check if ports exist
  • `` - Show ports if they exist
  • `` - Otherwise…
  • No ports exposed - Show this message
  • `` - Close the conditional

String Functions

Go templates support various string manipulation functions:

# Uppercase container names
docker ps --format " | "

# Truncate long image names
docker ps --format " | "

# Count characters in ports field
docker ps --format " has  port characters"

Advanced Conditional Examples

# Show health status when available
docker ps --format ": ✅ Healthy❌ Unhealthy⚪ Unknown"

# Highlight different container states
docker ps --format " [🟢 RUNNING🔴 STOPPED]"

Powerful Filtering Options

Docker’s filtering capabilities are incredibly sophisticated:

Status-Based Filtering

# Only running containers
docker ps -f "status=running"

# Only stopped containers
docker ps -f "status=exited"

# Only paused containers
docker ps -f "status=paused"

Name and Image Filtering

# Containers with "web" in the name
docker ps -f "name=web"

# Containers from nginx image
docker ps -f "ancestor=nginx"

# Containers exposing port 80
docker ps -f "expose=80"

Advanced Multi-Filter Combinations

# Running containers with "api" in name, showing custom format
docker ps -f "status=running" -f "name=api" --format "table \t\t"

# All containers from specific image with custom output
docker ps -a -f "ancestor=postgres" --format " | Created: "

JSON Output for Scripting

For automation and scripting, JSON format is invaluable:

docker ps --format json | jq '.[] | {name: .Names, status: .Status}'

This outputs clean JSON that can be processed by tools like jq, python, or any JSON parser.

Command-Line Flags Deep Dive

Essential Flags

Flag Description Example
-a, --all Show all containers docker ps -a
-q, --quiet Only container IDs docker ps -q
-s, --size Include file sizes docker ps -s
-n, --last Show last N containers docker ps -n 5
-l, --latest Show latest container docker ps -l
--no-trunc Don’t truncate output docker ps --no-trunc

Practical Flag Combinations

# Get IDs of all running containers
docker ps -q

# Show file sizes with custom format
docker ps -s --format "table \t\t"

# Last 3 containers with full details
docker ps -n 3 --no-trunc

Real-World Use Cases

1. Container Health Dashboard

Create a health monitoring view:

docker ps --format "table \t\tInternal" | grep -E "(healthy|unhealthy|starting)"

2. Port Mapping Overview

Quick port mapping check:

docker ps --format "table \t" | grep -v "^NAMES"

3. Resource Usage Summary

Monitor container sizes:

docker ps -s --format "table \t\t"

4. Development Environment Status

Perfect for checking your dev stack:

docker ps -f "name=dev-" --format " |  | ✅ Accessible❌ Internal"

Shell Integration and Aliases

Make these commands part of your daily workflow:

Bash/Zsh Aliases

Add to your ~/.bashrc or ~/.zshrc:

# Essential aliases
alias dps='docker ps --format "table \t\t"'
alias dpsa='docker ps -a --format "table \t\t"'
alias dpsq='docker ps -q'
alias dpsh='docker ps --format "table \t" | grep healthy'

# Advanced aliases
alias docker-health='docker ps --format "table \t" | grep -E "(healthy|unhealthy)"'
alias docker-ports='docker ps --format "table \t" | grep -v "^NAMES"'
alias docker-sizes='docker ps -s --format "table \t\t"'

Shell Functions

For more complex operations:

# Function to show containers by image
docker-by-image() {
    docker ps -f "ancestor=$1" --format "table \t\t"
}

# Function to show container resource usage
docker-resources() {
    docker ps -s --format "table \t\t" | head -${1:-10}
}

Troubleshooting and Tips

Common Template Errors

  1. Missing dots: Always use .FieldName, not FieldName
  2. Case sensitivity: Field names are case-sensitive (, not)
  3. Escaping quotes: Use \" for literal quotes in templates
  4. Tab characters: Use \t for proper column separation

Performance Considerations

  • Use -q flag when you only need container IDs
  • Combine filters to reduce output processing
  • Use --no-trunc sparingly on systems with many containers

Cross-Platform Compatibility

These formatting techniques work identically on:

  • Linux
  • macOS
  • Windows (with Docker Desktop)
  • WSL2

Beyond Docker PS

The same formatting techniques work with other Docker commands:

# Docker images with custom format
docker images --format "table \t\t"

# Docker networks
docker network ls --format "table \t\t"

# Docker volumes
docker volume ls --format "table \t\t"

Conclusion

Mastering docker ps formatting transforms a basic listing command into a powerful container management tool. With Go templates, you can:

  • Customize output to show exactly what you need
  • Filter containers with surgical precision
  • Create reusable aliases for common operations
  • Integrate seamlessly with shell scripts and automation

The techniques covered in this guide will save you time, reduce cognitive load, and make your Docker workflow more efficient. Start with simple custom formats and gradually incorporate advanced features as you become comfortable with the syntax.

Remember: the goal isn’t to memorize every template function, but to understand the patterns so you can craft the perfect view for each situation.

Quick Reference Card

# Essential formats
docker ps --format "table \t\t"
docker ps --format ": "
docker ps --format json

# Useful filters
docker ps -f "status=running"
docker ps -f "name=web"
docker ps -f "ancestor=nginx"

# Handy flags
docker ps -q              # Only IDs
docker ps -a              # All containers
docker ps -s              # Include sizes
docker ps --no-trunc      # Full output

Start experimenting with these techniques today, and watch your Docker productivity soar!

Want to dive deeper into Docker? Check out our other guides on Docker Compose orchestration, multi-stage builds, and production deployment strategies.

Updated:

You may also enjoy