.TH "DOCKER" "1" "Feb 2021" "Docker Community" "" 
.nh
.ad l


.SH NAME
.PP
docker\-container\-ls \- List containers


.SH SYNOPSIS
.PP
\fBdocker container ls [OPTIONS]\fP


.SH DESCRIPTION
.PP
List the containers in the local repository. By default this shows only
the running containers.

.SH Filters
.PP
Filter output based on these conditions:
   \- ancestor=(<image-name>[:tag]|<image-id>|
\[la]image@digest\[ra])
     containers created from an image or a descendant.
   \- before=(<container-name>|<container-id>)
   \- expose=(<port>[/<proto>]|<startport-endport>/[<proto>])
   \- exited=<int> an exit code of <int>
   \- health=(starting|healthy|unhealthy|none)
   \- id=<ID> a container's ID
   \- isolation=(\fB\fCdefault\fR|\fB\fCprocess\fR|\fB\fChyperv\fR) (Windows daemon only)
   \- is\-task=(true|false)
   \- label=<key> or label=<key>=<value>
   \- name=<string> a container's name
   \- network=(<network-id>|<network-name>)
   \- publish=(<port>[/<proto>]|<startport-endport>/[<proto>])
   \- since=(<container-name>|<container-id>)
   \- status=(created|restarting|removing|running|paused|exited)
   \- volume=(<volume name>|<mount point destination>)

.SH Format
.PP
The formatting option (\fB\-\-format\fP) pretty\-prints container output
using a Go template.

.PP
Valid placeholders for the Go template are listed below:
   \- .ID           \- Container ID.
   \- .Image        \- Image ID.
   \- .Command      \- Quoted command.
   \- .CreatedAt    \- Time when the container was created.
   \- .RunningFor   \- Elapsed time since the container was started.
   \- .Ports        \- Exposed ports.
   \- .Status       \- Container status.
   \- .Size         \- Container disk size.
   \- .Names        \- Container names.
   \- .Labels       \- All labels assigned to the container.
   \- .Label        \- Value of a specific label for this container.
                     For example \fB\&'{{.Label "com.docker.swarm.cpu"}}'\fP\&.
   \- .Mounts       \- Names of the volumes mounted in this container.
   \- .Networks     \- Names of the networks attached to this container.


.SH EXAMPLES
.SH Display all containers, including non\-running
.PP
.RS

.nf
$ docker container ls \-a
CONTAINER ID        IMAGE                 COMMAND                CREATED             STATUS      PORTS    NAMES
a87ecb4f327c        fedora:20             /bin/sh \-c #(nop) MA   20 minutes ago      Exit 0               desperate\_brattain
01946d9d34d8        vpavlin/rhel7:latest  /bin/sh \-c #(nop) MA   33 minutes ago      Exit 0               thirsty\_bell
c1d3b0166030        acffc0358b9e          /bin/sh \-c yum \-y up   2 weeks ago         Exit 1               determined\_torvalds
41d50ecd2f57        fedora:20             /bin/sh \-c #(nop) MA   2 weeks ago         Exit 0               drunk\_pike

.fi
.RE

.SH Display only IDs of all containers, including non\-running
.PP
.RS

.nf
$ docker container ls \-a \-q
a87ecb4f327c
01946d9d34d8
c1d3b0166030
41d50ecd2f57

.fi
.RE

.SH Display only IDs of all containers that have the name \fB\fCdetermined\_torvalds\fR
.PP
.RS

.nf
$ docker container ls \-a \-q \-\-filter=name=determined\_torvalds
c1d3b0166030

.fi
.RE

.SH Display containers with their commands
.PP
.RS

.nf
$ docker container ls \-\-format "{{.ID}}: {{.Command}}"
a87ecb4f327c: /bin/sh \-c #(nop) MA
01946d9d34d8: /bin/sh \-c #(nop) MA
c1d3b0166030: /bin/sh \-c yum \-y up
41d50ecd2f57: /bin/sh \-c #(nop) MA

.fi
.RE

.SH Display containers with their labels in a table
.PP
.RS

.nf
$ docker container ls \-\-format "table {{.ID}}\\t{{.Labels}}"
CONTAINER ID        LABELS
a87ecb4f327c        com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
01946d9d34d8
c1d3b0166030        com.docker.swarm.node=debian,com.docker.swarm.cpu=6
41d50ecd2f57        com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd

.fi
.RE

.SH Display containers with their node label in a table
.PP
.RS

.nf
$ docker container ls \-\-format 'table {{.ID}}\\t{{(.Label "com.docker.swarm.node")}}'
CONTAINER ID        NODE
a87ecb4f327c        ubuntu
01946d9d34d8
c1d3b0166030        debian
41d50ecd2f57        fedora

.fi
.RE

.SH Display containers with \fB\fCremote\-volume\fR mounted
.PP
.RS

.nf
$ docker container ls \-\-filter volume=remote\-volume \-\-format "table {{.ID}}\\t{{.Mounts}}"
CONTAINER ID        MOUNTS
9c3527ed70ce        remote\-volume

.fi
.RE

.SH Display containers with a volume mounted in \fB\fC/data\fR
.PP
.RS

.nf
$ docker container ls \-\-filter volume=/data \-\-format "table {{.ID}}\\t{{.Mounts}}"
CONTAINER ID        MOUNTS
9c3527ed70ce        remote\-volume

.fi
.RE

.SH Display containers that have published port of 80:
.PP
.RS

.nf
$ docker ps \-\-filter publish=80
CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS                   NAMES
fc7e477723b7        busybox             "top"               About a minute ago   Up About a minute   0.0.0.0:32768\->80/tcp   admiring\_roentgen

.fi
.RE

.SH Display containers that have exposed TCP port in the range of \fB\fC8000\-8080\fR:
.PP
.RS

.nf
$ docker ps \-\-filter expose=8000\-8080/tcp
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
9833437217a5        busybox             "top"               21 seconds ago      Up 19 seconds       8080/tcp            dreamy\_mccarthy

.fi
.RE


.SH OPTIONS
.PP
\fB\-a\fP, \fB\-\-all\fP[=false]
    Show all containers (default shows just running)

.PP
\fB\-f\fP, \fB\-\-filter\fP=
    Filter output based on conditions provided

.PP
\fB\-\-format\fP=""
    Pretty\-print containers using a Go template

.PP
\fB\-h\fP, \fB\-\-help\fP[=false]
    help for ls

.PP
\fB\-n\fP, \fB\-\-last\fP=\-1
    Show n last created containers (includes all states)

.PP
\fB\-l\fP, \fB\-\-latest\fP[=false]
    Show the latest created container (includes all states)

.PP
\fB\-\-no\-trunc\fP[=false]
    Don't truncate output

.PP
\fB\-q\fP, \fB\-\-quiet\fP[=false]
    Only display numeric IDs

.PP
\fB\-s\fP, \fB\-\-size\fP[=false]
    Display total file sizes


.SH SEE ALSO
.PP
\fBdocker\-container(1)\fP