Skip to main content

​
GetDockerStat

Retrieves basic information about all Docker containers on the system. 
func GetDockerStat() ([]CgroupDockerStat, error)
func GetDockerStatWithContext(ctx context.Context) ([]CgroupDockerStat, error)

​
Returns

Returns a slice of CgroupDockerStat structs containing:
FieldTypeDescription
ContainerIDstringFull Docker container ID (no truncation)
NamestringContainer name (first name if multiple)
ImagestringDocker image name
StatusstringContainer status (e.g., “Up 2 hours”)
RunningboolWhether container is currently running

​
Example

import (
    "fmt"
    "log"
    "github.com/shirou/gopsutil/v4/docker"
)

func main() {
    containers, err := docker.GetDockerStat()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d containers:\n", len(containers))
    for _, c := range containers {
        fmt.Printf("\n%s\n", c.Name)
        fmt.Printf("  ID: %s\n", c.ContainerID[:12])
        fmt.Printf("  Image: %s\n", c.Image)
        fmt.Printf("  Status: %s\n", c.Status)
        if c.Running {
            fmt.Println("  State: RUNNING")
        } else {
            fmt.Println("  State: STOPPED")
        }
    }
}

​
Implementation Details

This function executes: 
docker ps -a --no-trunc --format "{{.ID}}|{{.Image}}|{{.Names}}|{{.Status}}"
The --no-trunc flag ensures full container IDs are returned, which is necessary for cgroup filesystem operations.

​
Errors

  • Returns ErrDockerNotAvailable if Docker is not installed
  • Returns command execution errors if Docker daemon is not accessible

​
GetDockerIDList

Retrieves only the container IDs of running Docker containers. 
func GetDockerIDList() ([]string, error)
func GetDockerIDListWithContext(ctx context.Context) ([]string, error)

​
Returns

Returns a slice of full container ID strings (not truncated).

​
Example

import (
    "fmt"
    "log"
    "github.com/shirou/gopsutil/v4/docker"
)

func main() {
    ids, err := docker.GetDockerIDList()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Running containers: %d\n", len(ids))
    for _, id := range ids {
        fmt.Printf("  %s\n", id[:12]) // Display short ID
    }
}

​
Implementation Details

This function executes: 
docker ps -q --no-trunc
This function only returns running containers, unlike GetDockerStat which returns all containers (including stopped ones).

​
Use Cases

Batch Monitoring

Get IDs to iterate through and collect statistics for all running containers

Quick Count

Efficiently count running containers without parsing full metadata

​
Errors

  • Returns ErrDockerNotAvailable if Docker is not installed
  • Returns command execution errors if Docker daemon is not accessible

​
CgroupDockerStat Type

The main data structure for container information. 
type CgroupDockerStat struct {
    ContainerID string `json:"containerID"`
    Name        string `json:"name"`
    Image       string `json:"image"`
    Status      string `json:"status"`
    Running     bool   `json:"running"`
}

​
JSON Serialization

The struct includes a String() method that returns JSON representation: 
container := containers[0]
fmt.Println(container.String())
// Output: {"containerID":"abc123...","name":"my-app","image":"nginx:latest","status":"Up 2 hours","running":true}

​
Context Support

All functions have WithContext variants that accept context.Context for timeout and cancellation control.
import (
    "context"
    "time"
    "github.com/shirou/gopsutil/v4/docker"
)

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

containers, err := docker.GetDockerStatWithContext(ctx)
if err != nil {
    // Handle timeout or cancellation
}

Build docs developers (and LLMs) love

Get started for freeTalk to us