mirror of
https://github.com/docker/cli.git
synced 2026-10-08 06:56:31 -04:00
Yoan Wainmann
d573c171fe
Document how multiple --filter flags interact in prune commands: different filter keys are ANDed (all conditions must match), while multiple values for the same key are ORed (any value can match). This addresses a gap in the documentation where users could not determine whether multiple filters were combined with AND or OR logic, which is especially important for prune commands where the wrong assumption could lead to unintended data removal. Closes #5899 Signed-off-by: Yoan Wainmann <yoan@mreshet.co.il>
125 lines
5.3 KiB
Markdown
125 lines
5.3 KiB
Markdown
# container prune
|
||
|
||
<!---MARKER_GEN_START-->
|
||
Remove all stopped containers
|
||
|
||
### Options
|
||
|
||
| Name | Type | Default | Description |
|
||
|:----------------------|:---------|:--------|:-------------------------------------------------|
|
||
| [`--filter`](#filter) | `filter` | | Provide filter values (e.g. `until=<timestamp>`) |
|
||
| `-f`, `--force` | `bool` | | Do not prompt for confirmation |
|
||
|
||
|
||
<!---MARKER_GEN_END-->
|
||
|
||
## Description
|
||
|
||
Removes all stopped containers.
|
||
|
||
## Examples
|
||
|
||
### Prune containers
|
||
|
||
```console
|
||
$ docker container prune
|
||
WARNING! This will remove all stopped containers.
|
||
Are you sure you want to continue? [y/N] y
|
||
Deleted Containers:
|
||
4a7f7eebae0f63178aff7eb0aa39cd3f0627a203ab2df258c1a00b456cf20063
|
||
f98f9c2aa1eaf727e4ec9c0283bc7d4aa4762fbdba7f26191f26c97f64090360
|
||
|
||
Total reclaimed space: 212 B
|
||
```
|
||
|
||
### <a name="filter"></a> Filtering (--filter)
|
||
|
||
The filtering flag (`--filter`) format is of "key=value". If there is more
|
||
than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).
|
||
|
||
When multiple filters are provided, they are combined as follows:
|
||
|
||
- Multiple filters with **different keys** are combined using AND logic.
|
||
A container must satisfy all filter conditions to be pruned.
|
||
- Multiple filters with the **same key** are combined using OR logic.
|
||
A container is pruned if it matches any of the values for that key.
|
||
|
||
For example, `--filter "label=foo" --filter "until=24h"` prunes containers
|
||
that have the `foo` label **and** were created more than 24 hours ago.
|
||
Conversely, `--filter "label=foo" --filter "label=bar"` prunes containers
|
||
that have **either** the `foo` **or** `bar` label.
|
||
|
||
The currently supported filters are:
|
||
|
||
* until (`<timestamp>`) - only remove containers created before given timestamp
|
||
* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove containers with (or without, in case `label!=...` is used) the specified labels.
|
||
|
||
The `until` filter can be Unix timestamps, date formatted
|
||
timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed
|
||
relative to the daemon machine’s time. Supported formats for date
|
||
formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`,
|
||
`2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local
|
||
timezone on the daemon will be used if you do not provide either a `Z` or a
|
||
`+-00:00` timezone offset at the end of the timestamp. When providing Unix
|
||
timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
|
||
that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
|
||
seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
|
||
fraction of a second no more than nine digits long.
|
||
|
||
The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`),
|
||
which removes containers with the specified labels. The other
|
||
format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
|
||
containers without the specified labels.
|
||
|
||
The following removes containers created more than 5 minutes ago:
|
||
|
||
```console
|
||
$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'
|
||
|
||
CONTAINER ID IMAGE COMMAND CREATED AT STATUS
|
||
61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 41 seconds ago
|
||
53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 12 minutes ago
|
||
|
||
$ docker container prune --force --filter "until=5m"
|
||
|
||
Deleted Containers:
|
||
53a9bc23a5168b6caa2bfbefddf1b30f93c7ad57f3dec271fd32707497cb9369
|
||
|
||
Total reclaimed space: 25 B
|
||
|
||
$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'
|
||
|
||
CONTAINER ID IMAGE COMMAND CREATED AT STATUS
|
||
61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 44 seconds ago
|
||
```
|
||
|
||
The following removes containers created before `2017-01-04T13:10:00`:
|
||
|
||
```console
|
||
$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'
|
||
|
||
CONTAINER ID IMAGE COMMAND CREATED AT STATUS
|
||
53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 7 minutes ago
|
||
4a75091a6d61 busybox "sh" 2017-01-04 13:09:53 -0800 PST Exited (0) 9 minutes ago
|
||
|
||
$ docker container prune --force --filter "until=2017-01-04T13:10:00"
|
||
|
||
Deleted Containers:
|
||
4a75091a6d618526fcd8b33ccd6e5928ca2a64415466f768a6180004b0c72c6c
|
||
|
||
Total reclaimed space: 27 B
|
||
|
||
$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'
|
||
|
||
CONTAINER ID IMAGE COMMAND CREATED AT STATUS
|
||
53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 9 minutes ago
|
||
```
|
||
|
||
## Related commands
|
||
|
||
* [system df](system_df.md)
|
||
* [volume prune](volume_prune.md)
|
||
* [image prune](image_prune.md)
|
||
* [network prune](network_prune.md)
|
||
* [system prune](system_prune.md)
|