Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4755 from dvdksn/cli-reference-canonical 

docs: rename reference docs to "object_action"
This commit is contained in:
Sebastiaan van Stijn 2024-01-16 15:29:04 +01:00 committed by GitHub
parent ca58fdf5a1 37f5515666
commit a18dad3832
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
72 changed files with 5527 additions and 5945 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
docs/reference/commandline/attach.md
View File

@ -1,4 +1,4 @@
# attach # docker attach
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Attach local standard input, output, and error streams to a running container Attach local standard input, output, and error streams to a running container
@ -9,159 +9,12 @@ Attach local standard input, output, and error streams to a running container
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:--------------------------------|:---------|:--------|:----------------------------------------------------| |:----------------|:---------|:--------|:----------------------------------------------------|
| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | | `--detach-keys` | `string` | | Override the key sequence for detaching a container |
| `--no-stdin` | | | Do not attach STDIN | | `--no-stdin` | | | Do not attach STDIN |
| `--sig-proxy` | | | Proxy all received signals to the process | | `--sig-proxy` | | | Proxy all received signals to the process |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
Use `docker attach` to attach your terminal's standard input, output, and error
(or any combination of the three) to a running container using the container's
ID or name. This lets you view its output or control it interactively, as
though the commands were running directly in your terminal.
> **Note**
>
> The `attach` command displays the output of the container's `ENTRYPOINT` and
> `CMD` process. This can appear as if the attach command is hung when in fact
> the process may simply not be writing any output at that time.
You can attach to the same contained process multiple times simultaneously,
from different sessions on the Docker host.
To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the
container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to
the container. If the container was run with `-i` and `-t`, you can detach from
a container and leave it running using the `CTRL-p CTRL-q` key sequence.
> **Note**
>
> A process running as PID 1 inside a container is treated specially by
> Linux: it ignores any signal with the default action. So, the process
> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.
You can't redirect the standard input of a `docker attach` command while
attaching to a TTY-enabled container (using the `-i` and `-t` options).
While a client is connected to container's `stdio` using `docker attach`,
Docker uses a ~1MB memory buffer to maximize the throughput of the application.
Once this buffer is full, the speed of the API connection is affected, and so
this impacts the output process' writing speed. This is similar to other
applications like SSH. Because of this, it isn't recommended to run
performance-critical applications that generate a lot of output in the
foreground over a slow client connection. Instead, use the `docker logs`
command to get access to the logs.
## Examples
### Attach to and detach from a running container
The following example starts an Alpine container running `top` in detached mode,
then attaches to the container;
```console
$ docker run -d --name topdemo alpine top -b
$ docker attach topdemo
Mem: 2395856K used, 5638884K free, 2328K shrd, 61904K buff, 1524264K cached
CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq
Load average: 0.15 0.06 0.01 1/567 6
PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
1 0 root R 1700 0% 3 0% top -b
```
As the container was started without the `-i`, and `-t` options, signals are
forwarded to the attached process, which means that the default `CTRL-p CTRL-q`
detach key sequence produces no effect, but pressing `CTRL-c` terminates the
container:
```console
<...>
PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
1 0 root R 1700 0% 7 0% top -b
^P^Q
^C
$ docker ps -a --filter name=topdemo
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
96254a235bd6 alpine "top -b" 44 seconds ago Exited (130) 8 seconds ago topdemo
```
Repeating the example above, but this time with the `-i` and `-t` options set;
```console
$ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b
```
Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read
escape sequence"), the Docker CLI is handling the detach sequence, and the
`attach` command is detached from the container. Checking the container's status
with `docker ps` shows that the container is still running in the background:
```console
$ docker attach topdemo2
Mem: 2405344K used, 5629396K free, 2512K shrd, 65100K buff, 1524952K cached
CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq
Load average: 0.12 0.12 0.05 1/594 6
PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
1 0 root R 1700 0% 3 0% top -b
read escape sequence
$ docker ps -a --filter name=topdemo2
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
fde88b83c2c2 alpine "top -b" 22 seconds ago Up 21 seconds topdemo2
```
### Get the exit code of the container's command
And in this second example, you can see the exit code returned by the `bash`
process is returned by the `docker attach` command to its caller too:
```console
$ docker run --name test -dit alpine
275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab
$ docker attach test
/# exit 13
$ echo $?
13
$ docker ps -a --filter name=test
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test
```
### <a name="detach-keys"></a> Override the detach sequence (--detach-keys)
Use the `--detach-keys` option to override the Docker key sequence for detach.
This is useful if the Docker default sequence conflicts with key sequence you
use for other applications. There are two ways to define your own detach key
sequence, as a per-container override or as a configuration property on your
entire configuration.
To override the sequence for an individual container, use the
`--detach-keys="<sequence>"` flag with the `docker attach` command. The format of
the `<sequence>` is either a letter [a-Z], or the `ctrl-` combined with any of
the following:
* `a-z` (a single lowercase alpha character )
* `@` (at sign)
* `[` (left bracket)
* `\\` (two backward slashes)
* `_` (underscore)
* `^` (caret)
These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key
sequences. To configure a different configuration default key sequence for all
containers, see [**Configuration file** section](cli.md#configuration-files).

781
docs/reference/commandline/build.md
View File

@ -1,4 +1,4 @@
# build # docker build
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Build an image from a Dockerfile Build an image from a Dockerfile
@ -9,754 +9,39 @@ Build an image from a Dockerfile
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:------------------------------------|:--------------|:----------|:------------------------------------------------------------------| |:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) | | `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
| [`--build-arg`](#build-arg) | `list` | | Set build-time variables | | `--build-arg` | `list` | | Set build-time variables |
| [`--cache-from`](#cache-from) | `stringSlice` | | Images to consider as cache sources | | `--cache-from` | `stringSlice` | | Images to consider as cache sources |
| [`--cgroup-parent`](#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build | | `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build |
| `--compress` | | | Compress the build context using gzip | | `--compress` | | | Compress the build context using gzip |
| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period | | `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota | | `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | | `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | | `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | | `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
| `--disable-content-trust` | | | Skip image verification | | `--disable-content-trust` | | | Skip image verification |
| [`-f`](#file), [`--file`](#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) | | `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
| `--force-rm` | | | Always remove intermediate containers | | `--force-rm` | | | Always remove intermediate containers |
| `--iidfile` | `string` | | Write the image ID to the file | | `--iidfile` | `string` | | Write the image ID to the file |
| [`--isolation`](#isolation) | `string` | | Container isolation technology | | `--isolation` | `string` | | Container isolation technology |
| `--label` | `list` | | Set metadata for an image | | `--label` | `list` | | Set metadata for an image |
| `-m`, `--memory` | `bytes` | `0` | Memory limit | | `-m`, `--memory` | `bytes` | `0` | Memory limit |
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | | `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
| [`--network`](#network) | `string` | `default` | Set the networking mode for the RUN instructions during build | | `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build |
| `--no-cache` | | | Do not use cache when building the image | | `--no-cache` | | | Do not use cache when building the image |
| `--platform` | `string` | | Set platform if server is multi-platform capable | | `--platform` | `string` | | Set platform if server is multi-platform capable |
| `--pull` | | | Always attempt to pull a newer version of the image | | `--pull` | | | Always attempt to pull a newer version of the image |
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | | `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
| `--rm` | | | Remove intermediate containers after a successful build | | `--rm` | | | Remove intermediate containers after a successful build |
| [`--security-opt`](#security-opt) | `stringSlice` | | Security options | | `--security-opt` | `stringSlice` | | Security options |
| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | | `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
| [`--squash`](#squash) | | | Squash newly built layers into a single new layer | | `--squash` | | | Squash newly built layers into a single new layer |
| [`-t`](#tag), [`--tag`](#tag) | `list` | | Name and optionally a tag in the `name:tag` format | | `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format |
| [`--target`](#target) | `string` | | Set the target build stage to build. | | `--target` | `string` | | Set the target build stage to build. |
| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | | `--ulimit` | `ulimit` | | Ulimit options |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker build` command builds Docker images from a Dockerfile and a
"context". A build's context is the set of files located in the specified
`PATH` or `URL`. The build process can refer to any of the files in the
context. For example, your build can use a [*COPY*](https://docs.docker.com/engine/reference/builder/#copy)
instruction to reference a file in the context.
The `URL` parameter can refer to three kinds of resources: Git repositories,
pre-packaged tarball contexts, and plain text files.
### Git repositories
When the `URL` parameter points to the location of a Git repository, the
repository acts as the build context. The system recursively fetches the
repository and its submodules. The commit history isn't preserved. A
repository is first pulled into a temporary directory on your local host. After
that succeeds, the command sends the directory to the Docker daemon as the context.
Local copy gives you the ability to access private repositories using local
user credentials, VPNs, and so forth.
> **Note**
>
> If the `URL` parameter contains a fragment the system recursively clones
> the repository and its submodules using a `git clone --recursive` command.
Git URLs accept context configuration in their fragment section, separated by a
colon (`:`). The first part represents the reference that Git checks out,
and can be either a branch, a tag, or a remote reference. The second part
represents a subdirectory inside the repository used as a build
context.
For example, run this command to use a directory called `docker` in the branch
`container`:
```console
$ docker build https://github.com/docker/rootfs.git#container:docker
```
The following table represents all the valid suffixes with their build
contexts:
| Build Syntax Suffix | Commit Used | Build Context Used |
|--------------------------------|-----------------------|--------------------|
| `myrepo.git` | `refs/heads/master` | `/` |
| `myrepo.git#mytag` | `refs/tags/mytag` | `/` |
| `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` |
| `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` |
| `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` |
| `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` |
| `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` |
| `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` |
### Tarball contexts
If you pass a URL to a remote tarball, the command sends the URL itself to the
daemon:
```console
$ docker build http://server/context.tar.gz
```
The host running the Docker daemon performs the download operation,
which isn't necessarily the same host that issued the build command.
The Docker daemon fetches `context.tar.gz` and uses it as the
build context. Tarball contexts must be tar archives conforming to the standard
`tar` Unix format and can be compressed with any one of the `xz`, `bzip2`,
`gzip` or `identity` (no compression) formats.
### Text files
Instead of specifying a context, you can pass a single `Dockerfile` in the
`URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`:
```console
$ docker build - < Dockerfile
```
With PowerShell on Windows, you run:
```powershell
Get-Content Dockerfile | docker build -
```
If you use `STDIN` or specify a `URL` pointing to a plain text file, the daemon
places the contents into a `Dockerfile`, and ignores any `-f`, `--file`
option. In this scenario, there is no context.
By default the `docker build` command looks for a `Dockerfile` at the root
of the build context. The `-f`, `--file`, option lets you specify the path to
an alternative file to use instead. This is useful in cases that use the same
set of files for multiple builds. The path must be to a file within the
build context. Relative path are interpreted as relative to the root of the
context.
In most cases, it's best to put each Dockerfile in an empty directory. Then,
add to that directory only the files needed for building the Dockerfile. To
increase the build's performance, you can exclude files and directories by
adding a `.dockerignore` file to that directory as well. For information on
creating one, see the [.dockerignore file](https://docs.docker.com/engine/reference/builder/#dockerignore-file).
If the Docker client loses connection to the daemon, it cancels the build.
This happens if you interrupt the Docker client with `CTRL-c` or if the Docker
client is killed for any reason. If the build initiated a pull which is still
running at the time the build is cancelled, the client also cancels the pull.
## Return code
Successful builds return exit code `0`. When the build fails, the command
returns a non-zero exit code and prints an error message to `STDERR`:
```console
$ docker build -t fail .
Sending build context to Docker daemon 2.048 kB
Sending build context to Docker daemon
Step 1/3 : FROM busybox
---> 4986bf8c1536
Step 2/3 : RUN exit 13
---> Running in e26670ec7a0a
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
$ echo $?
1
```
See also:
[*Dockerfile Reference*](https://docs.docker.com/engine/reference/builder/).
## Examples
### Build with PATH
```console
$ docker build .
Uploading context 10240 bytes
Step 1/3 : FROM busybox
Pulling repository busybox
---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
Step 2/3 : RUN ls -lh /
---> Running in 9c9e81692ae9
total 24
drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin
drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev
drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib
lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib
dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc
lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin
dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys
drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr
---> b35f4035db3f
Step 3/3 : CMD echo Hello world
---> Running in 02071fceb21b
---> f52f38b7823e
Successfully built f52f38b7823e
Removing intermediate container 9c9e81692ae9
Removing intermediate container 02071fceb21b
```
This example specifies that the `PATH` is `.`, and so `tar`s all the files in the
local directory and sends them to the Docker daemon. The `PATH` specifies
where to find the files for the "context" of the build on the Docker daemon.
Remember that the daemon could be running on a remote machine and that no
parsing of the Dockerfile happens at the client side (where you're running
`docker build`). That means that all the files at `PATH` are sent, not just
the ones listed to [`ADD`](https://docs.docker.com/engine/reference/builder/#add)
in the Dockerfile.
The transfer of context from the local machine to the Docker daemon is what the
`docker` client means when you see the "Sending build context" message.
If you wish to keep the intermediate containers after the build is complete,
you must use `--rm=false`. This doesn't affect the build cache.
### Build with URL
```console
$ docker build github.com/creack/docker-firefox
```
This clones the GitHub repository, using the cloned repository as context,
and the Dockerfile at the root of the repository. You can
specify an arbitrary Git repository by using the `git://` or `git@` scheme.
```console
$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz
Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B
Step 1/3 : FROM busybox
---> 8c2e06607696
Step 2/3 : ADD ctx/container.cfg /
---> e7829950cee3
Removing intermediate container b35224abf821
Step 3/3 : CMD /bin/ls
---> Running in fbc63d321d73
---> 3286931702ad
Removing intermediate container fbc63d321d73
Successfully built 377c409b35e4
```
This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which
downloads and extracts the referenced tarball. The `-f ctx/Dockerfile`
parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` used
to build the image. Any `ADD` commands in that `Dockerfile` that refer to local
paths must be relative to the root of the contents inside `ctx.tar.gz`. In the
example above, the tarball contains a directory `ctx/`, so the `ADD
ctx/container.cfg /` operation works as expected.
### Build with `-`
```console
$ docker build - < Dockerfile
```
This example reads a Dockerfile from `STDIN` without context. Due to the lack of a
context, the command doesn't send contents of any local directory to the Docker daemon.
Since there is no context, a Dockerfile `ADD` only works if it refers to a
remote URL.
```console
$ docker build - < context.tar.gz
```
This example builds an image for a compressed context read from `STDIN`.
Supported formats are: `bzip2`, `gzip` and `xz`.
### Use a .dockerignore file
```console
$ docker build .
Uploading context 18.829 MB
Uploading context
Step 1/2 : FROM busybox
---> 769b9341d937
Step 2/2 : CMD echo Hello world
---> Using cache
---> 99cc1ad10469
Successfully built 99cc1ad10469
$ echo ".git" > .dockerignore
$ docker build .
Uploading context 6.76 MB
Uploading context
Step 1/2 : FROM busybox
---> 769b9341d937
Step 2/2 : CMD echo Hello world
---> Using cache
---> 99cc1ad10469
Successfully built 99cc1ad10469
```
This example shows the use of the `.dockerignore` file to exclude the `.git`
directory from the context. You can see its effect in the changed size of the
uploaded context. The builder reference contains detailed information on
[creating a .dockerignore file](https://docs.docker.com/engine/reference/builder/#dockerignore-file).
When using the [BuildKit backend](https://docs.docker.com/build/buildkit/),
`docker build` searches for a `.dockerignore` file relative to the Dockerfile
name. For example, running `docker build -f myapp.Dockerfile .` first looks
for an ignore file named `myapp.Dockerfile.dockerignore`. If it can't find such a file,
if present, it uses the `.dockerignore` file. Using a Dockerfile based
`.dockerignore` is useful if a project contains multiple Dockerfiles that expect
to ignore different sets of files.
### <a name="tag"></a> Tag an image (-t, --tag)
```console
$ docker build -t vieux/apache:2.0 .
```
This examples builds in the same way as the previous example, but it then tags the resulting
image. The repository name will be `vieux/apache` and the tag `2.0`.
[Read more about valid tags](tag.md).
You can apply multiple tags to an image. For example, you can apply the `latest`
tag to a newly built image and add another tag that references a specific
version.
For example, to tag an image both as `whenry/fedora-jboss:latest` and
`whenry/fedora-jboss:v2.1`, use the following:
```console
$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
```
### <a name="file"></a> Specify a Dockerfile (-f, --file)
```console
$ docker build -f Dockerfile.debug .
```
This uses a file called `Dockerfile.debug` for the build instructions
instead of `Dockerfile`.
```console
$ curl example.com/remote/Dockerfile | docker build -f - .
```
The above command uses the current directory as the build context and reads
a Dockerfile from stdin.
```console
$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod .
```
The above commands build the current build context (as specified by the
`.`) twice. Once using a debug version of a `Dockerfile` and once using a
production version.
```console
$ cd /home/me/myapp/some/dir/really/deep
$ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
$ docker build -f ../../../../dockerfiles/debug /home/me/myapp
```
These two `docker build` commands do the exact same thing. They both use the
contents of the `debug` file instead of looking for a `Dockerfile` and use
`/home/me/myapp` as the root of the build context. Note that `debug` is in the
directory structure of the build context, regardless of how you refer to it on
the command line.
> **Note**
>
> `docker build` returns a `no such file or directory` error if the
> file or directory doesn't exist in the uploaded context. This may
> happen if there is no context, or if you specify a file that's
> elsewhere on the Host system. The context is limited to the current
> directory (and its children) for security reasons, and to ensure
> repeatable builds on remote Docker hosts. This is also the reason why
> `ADD ../file` doesn't work.
### <a name="cgroup-parent"></a> Use a custom parent cgroup (--cgroup-parent)
When you run `docker build` with the `--cgroup-parent` option, the daemon runs the containers
used in the build with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups).
### <a name="ulimit"></a> Set ulimits in container (--ulimit)
Using the `--ulimit` option with `docker build` causes the daemon to start each build step's
container using those [`--ulimit` flag values](run.md#ulimit).
### <a name="build-arg"></a> Set build-time variables (--build-arg)
You can use `ENV` instructions in a Dockerfile to define variable values. These
values persist in the built image. Often persistence isn't what you want. Users
want to specify variables differently depending on which host they build an
image on.
A good example is `http_proxy` or source versions for pulling intermediate
files. The `ARG` instruction lets Dockerfile authors define values that users
can set at build-time using the `--build-arg` flag:
```console
$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .
```
This flag allows you to pass the build-time variables that are
accessed like regular environment variables in the `RUN` instruction of the
Dockerfile. These values don't persist in the intermediate or final images
like `ENV` values do. You must add `--build-arg` for each build argument.
Using this flag doesn't alter the output you see when the build process echoes the`ARG` lines from the
Dockerfile.
For detailed information on using `ARG` and `ENV` instructions, see the
[Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
You can also use the `--build-arg` flag without a value, in which case the daemon
propagates the value from the local environment into the Docker container it's building:
```console
$ export HTTP_PROXY=http://10.20.30.2:1234
$ docker build --build-arg HTTP_PROXY .
```
This example is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env)
for more information.
### <a name="security-opt"></a> Optional security options (--security-opt)
This flag is only supported on a daemon running on Windows, and only supports
the `credentialspec` option. The `credentialspec` must be in the format
`file://spec.txt` or `registry://keyname`.
### <a name="isolation"></a> Specify isolation technology for container (--isolation)
This option is useful in situations where you are running Docker containers on
Windows. The `--isolation=<value>` option sets a container's isolation
technology. On Linux, the only supported is the `default` option which uses
Linux namespaces. On Microsoft Windows, you can specify these values:
| Value | Description |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. |
| `process` | Namespace isolation only. |
| `hyperv` | Hyper-V hypervisor partition-based isolation. |
Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
### <a name="add-host"></a> Add entries to container hosts file (--add-host)
You can add other hosts into a build container's `/etc/hosts` file by using one
or more `--add-host` flags. This example adds static addresses for hosts named
`my-hostname` and `my_hostname_v6`:
```console
$ docker build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .
```
If you need your build to connect to services running on the host, you can use
the special `host-gateway` value for `--add-host`. In the following example,
build containers resolve `host.docker.internal` to the host's gateway IP.
```console
$ docker build --add-host host.docker.internal=host-gateway .
```
You can wrap an IPv6 address in square brackets.
`=` and `:` are both valid separators.
Both formats in the following example are valid:
```console
$ docker build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .
```
### <a name="target"></a> Specifying target build stage (--target)
When building a Dockerfile with multiple build stages, you can use the `--target`
option to specify an intermediate build stage by name as a final stage for the
resulting image. The daemon skips commands after the target stage.
```dockerfile
FROM debian AS build-env
# ...
FROM alpine AS production-env
# ...
```
```console
$ docker build -t mybuildimage --target build-env .
```
### <a name="output"></a> Custom build outputs (--output)
> **Note**
>
> This feature requires the BuildKit backend. You can either
> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
> use the [buildx](https://github.com/docker/buildx) plugin which provides more
> output type options.
By default, a local container image is created from the build result. The
`--output` (or `-o`) flag allows you to override this behavior, and specify a
custom exporter. Custom exporters allow you to export the build
artifacts as files on the local filesystem instead of a Docker image, which can
be useful for generating local binaries, code generation etc.
The value for `--output` is a CSV-formatted string defining the exporter type
and options that supports `local` and `tar` exporters.
The `local` exporter writes the resulting build files to a directory on the client side. The
`tar` exporter is similar but writes the files as a single tarball (`.tar`).
If you specify no type, the value defaults to the output directory of the local
exporter. Use a hyphen (`-`) to write the output tarball to standard output
(`STDOUT`).
The following example builds an image using the current directory (`.`) as a build
context, and exports the files to a directory named `out` in the current directory.
If the directory does not exist, Docker creates the directory automatically:
```console
$ docker build -o out .
```
The example above uses the short-hand syntax, omitting the `type` options, and
thus uses the default (`local`) exporter. The example below shows the equivalent
using the long-hand CSV syntax, specifying both `type` and `dest` (destination
path):
```console
$ docker build --output type=local,dest=out .
```
Use the `tar` type to export the files as a `.tar` archive:
```console
$ docker build --output type=tar,dest=out.tar .
```
The example below shows the equivalent when using the short-hand syntax. In this
case, `-` is specified as destination, which automatically selects the `tar` type,
and writes the output tarball to standard output, which is then redirected to
the `out.tar` file:
```console
$ docker build -o - . > out.tar
```
The `--output` option exports all files from the target stage. A common pattern
for exporting only specific files is to do multi-stage builds and to copy the
desired files to a new scratch stage with [`COPY --from`](https://docs.docker.com/engine/reference/builder/#copy).
The example, the `Dockerfile` below uses a separate stage to collect the
build artifacts for exporting:
```dockerfile
FROM golang AS build-stage
RUN go get -u github.com/LK4D4/vndr
FROM scratch AS export-stage
COPY --from=build-stage /go/bin/vndr /
```
When building the Dockerfile with the `-o` option, the command only exports the files from the final
stage to the `out` directory, in this case, the `vndr` binary:
```console
$ docker build -o out .
[+] Building 2.3s (7/7) FINISHED
=> [internal] load build definition from Dockerfile 0.1s
=> => transferring dockerfile: 176B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
=> [internal] load metadata for docker.io/library/golang:latest 1.6s
=> [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s
=> => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s
=> CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s
=> [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s
=> exporting to client 0.4s
=> => copying files 10.30MB 0.3s
$ ls ./out
vndr
```
### <a name="cache-from"></a> Specifying external cache sources (--cache-from)
> **Note**
>
> This feature requires the BuildKit backend. You can either
> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
> use the [buildx](https://github.com/docker/buildx) plugin. The previous
> builder has limited support for reusing cache from pre-pulled images.
In addition to local build cache, the builder can reuse the cache generated from
previous builds with the `--cache-from` flag pointing to an image in the registry.
To use an image as a cache source, cache metadata needs to be written into the
image on creation. You can do this by setting `--build-arg BUILDKIT_INLINE_CACHE=1`
when building the image. After that, you can use the built image as a cache source
for subsequent builds.
Upon importing the cache, the builder only pulls the JSON metadata from the
registry and determine possible cache hits based on that information. If there
is a cache hit, the builder pulls the matched layers into the local environment.
In addition to images, the cache can also be pulled from special cache manifests
generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI
(`buildctl`). These manifests (when built with the `type=registry` and `mode=max`
options) allow pulling layer data for intermediate stages in multi-stage builds.
The following example builds an image with inline-cache metadata and pushes it
to a registry, then uses the image as a cache source on another machine:
```console
$ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 .
$ docker push myname/myapp
```
After pushing the image, the image is used as cache source on another machine.
BuildKit automatically pulls the image from the registry if needed.
On another machine:
```console
$ docker build --cache-from myname/myapp .
```
### <a name="network"></a> Set the networking mode for the RUN instructions during build (--network)
#### Overview
Available options for the networking mode are:
- `default` (default): Run in the default network.
- `none`: Run with no network access.
- `host`: Run in the host’s network environment.
Find more details in the [Dockerfile documentation](https://docs.docker.com/engine/reference/builder/#run---network).
### <a name="squash"></a> Squash an image's layers (--squash) (experimental)
#### Overview
> **Note**
> The `--squash` option is an experimental feature, and should not be considered
> stable.
Once the image is built, this flag squashes the new layers into a new image with
a single new layer. Squashing doesn't destroy any existing image, rather it
creates a new image with the content of the squashed layers. This effectively
makes it look like all `Dockerfile` commands were created with a single layer.
The `--squash` flag preserves the build cache.
Squashing layers can be beneficial if your Dockerfile produces multiple layers
modifying the same files. For example, files created in one step and
removed in another step. For other use-cases, squashing images may actually have
a negative impact on performance. When pulling an image consisting of multiple
layers, the daemon can pull layers in parallel and allows sharing layers between
images (saving space).
For most use cases, multi-stage builds are a better alternative, as they give more
fine-grained control over your build, and can take advantage of future
optimizations in the builder. Refer to the [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
section for more information.
#### Known limitations
The `--squash` option has a number of known limitations:
- When squashing layers, the resulting image can't take advantage of layer
sharing with other images, and may use significantly more space. Sharing the
base image is still supported.
- When using this option you may see significantly more space used due to
storing two copies of the image, one for the build cache with all the cache
layers intact, and one for the squashed version.
- While squashing layers may produce smaller images, it may have a negative
impact on performance, as a single layer takes longer to extract, and
you can't parallelize downloading a single layer.
- When attempting to squash an image that doesn't make changes to the
filesystem (for example, the Dockerfile only contains `ENV` instructions),
the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)).
#### Prerequisites
The example on this page is using experimental mode in Docker 23.03.
You can enable experimental mode by using the `--experimental` flag when starting
the Docker daemon or setting `experimental: true` in the `daemon.json` configuration
file.
By default, experimental mode is disabled. To see the current configuration of
the Docker daemon, use the `docker version` command and check the `Experimental`
line in the `Engine` section:
```console
Client: Docker Engine - Community
Version: 23.0.3
API version: 1.42
Go version: go1.19.7
Git commit: 3e7cbfd
Built: Tue Apr 4 22:05:41 2023
OS/Arch: darwin/amd64
Context: default
Server: Docker Engine - Community
Engine:
Version: 23.0.3
API version: 1.42 (minimum version 1.12)
Go version: go1.19.7
Git commit: 59118bf
Built: Tue Apr 4 22:05:41 2023
OS/Arch: linux/amd64
Experimental: true
[...]
```
#### Build an image with the `--squash` flag
The following is an example of a build with the `--squash` flag. Below is the
`Dockerfile`:
```dockerfile
FROM busybox
RUN echo hello > /hello
RUN echo world >> /hello
RUN touch remove_me /remove_me
ENV HELLO=world
RUN rm /remove_me
```
Next, build an image named `test` using the `--squash` flag.
```console
$ docker build --squash -t test .
```
After the build completes, the history looks like the below. The history could show that a layer's
name is `<missing>`, and there is a new layer with COMMENT `merge`.
```console
$ docker history test
IMAGE CREATED CREATED BY SIZE COMMENT
4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb
<missing> 5 minutes ago /bin/sh -c rm /remove_me 0 B
<missing> 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B
<missing> 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B
<missing> 5 minutes ago /bin/sh -c echo world >> /hello 0 B
<missing> 6 minutes ago /bin/sh -c echo hello > /hello 0 B
<missing> 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B
<missing> 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB
```
Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is
in `/hello`, make sure the `HELLO` environment variable's value is `world`.

98
docs/reference/commandline/commit.md
View File

@ -1,4 +1,4 @@
# commit # docker commit
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Create a new image from a container's changes Create a new image from a container's changes
@ -9,97 +9,13 @@ Create a new image from a container's changes
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:-----------------------------------------------------------| |:------------------|:---------|:--------|:-----------------------------------------------------------|
| `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith <hannibal@a-team.com>`) | | `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| [`-c`](#change), [`--change`](#change) | `list` | | Apply Dockerfile instruction to the created image | | `-c`, `--change` | `list` | | Apply Dockerfile instruction to the created image |
| `-m`, `--message` | `string` | | Commit message | | `-m`, `--message` | `string` | | Commit message |
| `-p`, `--pause` | | | Pause container during commit | | `-p`, `--pause` | | | Pause container during commit |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
It can be useful to commit a container's file changes or settings into a new
image. This lets you debug a container by running an interactive shell, or
export a working dataset to another server.
Commits do not include any data contained in mounted volumes.
By default, the container being committed and its processes will be paused
while the image is committed. This reduces the likelihood of encountering data
corruption during the process of creating the commit. If this behavior is
undesired, set the `--pause` option to false.
The `--change` option will apply `Dockerfile` instructions to the image that's
created. Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
## Examples
### Commit a container
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
$ docker commit c3f279d17e0a svendowideit/testimage:version3
f5283438590d
$ docker images
REPOSITORY TAG ID CREATED SIZE
svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB
```
### <a name="change"></a> Commit a container with new configurations (--change)
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
$ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a
[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin]
$ docker commit --change "ENV DEBUG=true" c3f279d17e0a svendowideit/testimage:version3
f5283438590d
$ docker inspect -f "{{ .Config.Env }}" f5283438590d
[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true]
```
### Commit a container with new `CMD` and `EXPOSE` instructions
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
$ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4
f5283438590d
$ docker run -d svendowideit/testimage:version4
89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
```

158
docs/reference/commandline/container_attach.md
View File

@ -1,4 +1,4 @@
# container attach # attach
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Attach local standard input, output, and error streams to a running container Attach local standard input, output, and error streams to a running container
@ -9,15 +9,159 @@ Attach local standard input, output, and error streams to a running container
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------|:---------|:--------|:----------------------------------------------------| |:--------------------------------|:---------|:--------|:----------------------------------------------------|
| `--detach-keys` | `string` | | Override the key sequence for detaching a container | | [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container |
| `--no-stdin` | | | Do not attach STDIN | | `--no-stdin` | | | Do not attach STDIN |
| `--sig-proxy` | | | Proxy all received signals to the process | | `--sig-proxy` | | | Proxy all received signals to the process |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker attach](attach.md) for more information. Use `docker attach` to attach your terminal's standard input, output, and error
(or any combination of the three) to a running container using the container's
ID or name. This lets you view its output or control it interactively, as
though the commands were running directly in your terminal.
> **Note**
>
> The `attach` command displays the output of the container's `ENTRYPOINT` and
> `CMD` process. This can appear as if the attach command is hung when in fact
> the process may simply not be writing any output at that time.
You can attach to the same contained process multiple times simultaneously,
from different sessions on the Docker host.
To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the
container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to
the container. If the container was run with `-i` and `-t`, you can detach from
a container and leave it running using the `CTRL-p CTRL-q` key sequence.
> **Note**
>
> A process running as PID 1 inside a container is treated specially by
> Linux: it ignores any signal with the default action. So, the process
> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.
You can't redirect the standard input of a `docker attach` command while
attaching to a TTY-enabled container (using the `-i` and `-t` options).
While a client is connected to container's `stdio` using `docker attach`,
Docker uses a ~1MB memory buffer to maximize the throughput of the application.
Once this buffer is full, the speed of the API connection is affected, and so
this impacts the output process' writing speed. This is similar to other
applications like SSH. Because of this, it isn't recommended to run
performance-critical applications that generate a lot of output in the
foreground over a slow client connection. Instead, use the `docker logs`
command to get access to the logs.
## Examples
### Attach to and detach from a running container
The following example starts an Alpine container running `top` in detached mode,
then attaches to the container;
```console
$ docker run -d --name topdemo alpine top -b
$ docker attach topdemo
Mem: 2395856K used, 5638884K free, 2328K shrd, 61904K buff, 1524264K cached
CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq
Load average: 0.15 0.06 0.01 1/567 6
PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
1 0 root R 1700 0% 3 0% top -b
```
As the container was started without the `-i`, and `-t` options, signals are
forwarded to the attached process, which means that the default `CTRL-p CTRL-q`
detach key sequence produces no effect, but pressing `CTRL-c` terminates the
container:
```console
<...>
PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
1 0 root R 1700 0% 7 0% top -b
^P^Q
^C
$ docker ps -a --filter name=topdemo
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
96254a235bd6 alpine "top -b" 44 seconds ago Exited (130) 8 seconds ago topdemo
```
Repeating the example above, but this time with the `-i` and `-t` options set;
```console
$ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b
```
Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read
escape sequence"), the Docker CLI is handling the detach sequence, and the
`attach` command is detached from the container. Checking the container's status
with `docker ps` shows that the container is still running in the background:
```console
$ docker attach topdemo2
Mem: 2405344K used, 5629396K free, 2512K shrd, 65100K buff, 1524952K cached
CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq
Load average: 0.12 0.12 0.05 1/594 6
PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
1 0 root R 1700 0% 3 0% top -b
read escape sequence
$ docker ps -a --filter name=topdemo2
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
fde88b83c2c2 alpine "top -b" 22 seconds ago Up 21 seconds topdemo2
```
### Get the exit code of the container's command
And in this second example, you can see the exit code returned by the `bash`
process is returned by the `docker attach` command to its caller too:
```console
$ docker run --name test -dit alpine
275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab
$ docker attach test
/# exit 13
$ echo $?
13
$ docker ps -a --filter name=test
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test
```
### <a name="detach-keys"></a> Override the detach sequence (--detach-keys)
Use the `--detach-keys` option to override the Docker key sequence for detach.
This is useful if the Docker default sequence conflicts with key sequence you
use for other applications. There are two ways to define your own detach key
sequence, as a per-container override or as a configuration property on your
entire configuration.
To override the sequence for an individual container, use the
`--detach-keys="<sequence>"` flag with the `docker attach` command. The format of
the `<sequence>` is either a letter [a-Z], or the `ctrl-` combined with any of
the following:
* `a-z` (a single lowercase alpha character )
* `@` (at sign)
* `[` (left bracket)
* `\\` (two backward slashes)
* `_` (underscore)
* `^` (caret)
These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key
sequences. To configure a different configuration default key sequence for all
containers, see [**Configuration file** section](cli.md#configuration-files).

97
docs/reference/commandline/container_commit.md
View File

@ -1,4 +1,4 @@
# container commit # commit
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Create a new image from a container's changes Create a new image from a container's changes
@ -9,16 +9,97 @@ Create a new image from a container's changes
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:------------------|:---------|:--------|:-----------------------------------------------------------| |:---------------------------------------|:---------|:--------|:-----------------------------------------------------------|
| `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith <hannibal@a-team.com>`) | | `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| `-c`, `--change` | `list` | | Apply Dockerfile instruction to the created image | | [`-c`](#change), [`--change`](#change) | `list` | | Apply Dockerfile instruction to the created image |
| `-m`, `--message` | `string` | | Commit message | | `-m`, `--message` | `string` | | Commit message |
| `-p`, `--pause` | | | Pause container during commit | | `-p`, `--pause` | | | Pause container during commit |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker commit](commit.md) for more information. It can be useful to commit a container's file changes or settings into a new
image. This lets you debug a container by running an interactive shell, or
export a working dataset to another server.
Commits do not include any data contained in mounted volumes.
By default, the container being committed and its processes will be paused
while the image is committed. This reduces the likelihood of encountering data
corruption during the process of creating the commit. If this behavior is
undesired, set the `--pause` option to false.
The `--change` option will apply `Dockerfile` instructions to the image that's
created. Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
## Examples
### Commit a container
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
$ docker commit c3f279d17e0a svendowideit/testimage:version3
f5283438590d
$ docker images
REPOSITORY TAG ID CREATED SIZE
svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB
```
### <a name="change"></a> Commit a container with new configurations (--change)
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
$ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a
[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin]
$ docker commit --change "ENV DEBUG=true" c3f279d17e0a svendowideit/testimage:version3
f5283438590d
$ docker inspect -f "{{ .Config.Env }}" f5283438590d
[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true]
```
### Commit a container with new `CMD` and `EXPOSE` instructions
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
$ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4
f5283438590d
$ docker run -d svendowideit/testimage:version4
89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat
c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky
197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton
```

107
docs/reference/commandline/container_cp.md
View File

@ -1,4 +1,4 @@
# container cp # cp
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Copy files/folders between a container and the local filesystem Copy files/folders between a container and the local filesystem
@ -25,4 +25,107 @@ container source to stdout.
## Description ## Description
See [docker cp](cp.md) for more information. The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`.
You can copy from the container's file system to the local machine or the
reverse, from the local filesystem to the container. If `-` is specified for
either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from
`STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container.
The `SRC_PATH` or `DEST_PATH` can be a file or directory.
The `docker cp` command assumes container paths are relative to the container's
`/` (root) directory. This means supplying the initial forward slash is optional;
The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and
`compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can
be an absolute or relative value. The command interprets a local machine's
relative paths as relative to the current working directory where `docker cp` is
run.
The `cp` command behaves like the Unix `cp -a` command in that directories are
copied recursively with permissions preserved if possible. Ownership is set to
the user and primary group at the destination. For example, files copied to a
container are created with `UID:GID` of the root user. Files copied to the local
machine are created with the `UID:GID` of the user which invoked the `docker cp`
command. However, if you specify the `-a` option, `docker cp` sets the ownership
to the user and primary group at the source.
If you specify the `-L` option, `docker cp` follows any symbolic link
in the `SRC_PATH`. `docker cp` doesn't create parent directories for
`DEST_PATH` if they don't exist.
Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
argument of `DEST_PATH`, the behavior is as follows:
- `SRC_PATH` specifies a file
- `DEST_PATH` does not exist
- the file is saved to a file created at `DEST_PATH`
- `DEST_PATH` does not exist and ends with `/`
- Error condition: the destination directory must exist.
- `DEST_PATH` exists and is a file
- the destination is overwritten with the source file's contents
- `DEST_PATH` exists and is a directory
- the file is copied into this directory using the basename from
`SRC_PATH`
- `SRC_PATH` specifies a directory
- `DEST_PATH` does not exist
- `DEST_PATH` is created as a directory and the *contents* of the source
directory are copied into this directory
- `DEST_PATH` exists and is a file
- Error condition: cannot copy a directory to a file
- `DEST_PATH` exists and is a directory
- `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_)
- the source directory is copied into this directory
- `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_)
- the *content* of the source directory is copied into this
directory
The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above
rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
the target, is copied by default. To copy the link target and not the link, specify
the `-L` option.
A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can
also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local
machine, for example `file:name.txt`. If you use a `:` in a local machine path,
you must be explicit with a relative or absolute path, for example:
`/path/to/file:name.txt` or `./file:name.txt`
## Examples
Copy a local file into container
```console
$ docker cp ./some_file CONTAINER:/work
```
Copy files from container to local path
```console
$ docker cp CONTAINER:/var/logs/ /tmp/app_logs
```
Copy a file from container to stdout. Please note `cp` command produces a tar stream
```console
$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR"
```
### Corner cases
It isn't possible to copy certain system files such as resources under
`/proc`, `/sys`, `/dev`, [tmpfs](run.md#tmpfs), and mounts created by
the user in the container. However, you can still copy such files by manually
running `tar` in `docker exec`. Both of the following examples do the same thing
in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):
```console
$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
```
```console
$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH -
```
Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
The command extracts the content of the tar to the `DEST_PATH` in container's
filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as
the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.

84
docs/reference/commandline/container_create.md
View File

@ -1,4 +1,4 @@
# container create # create
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Create a new container Create a new container
@ -117,4 +117,84 @@ Create a new container
## Description ## Description
See [docker create](create.md) for more information. The `docker container create` (or shorthand: `docker create`) command creates a
new container from the specified image, without starting it.
When creating a container, the Docker daemon creates a writeable container layer
over the specified image and prepares it for running the specified command. The
container ID is then printed to `STDOUT`. This is similar to `docker run -d`
except the container is never started. You can then use the `docker container start`
(or shorthand: `docker start`) command to start the container at any point.
This is useful when you want to set up a container configuration ahead of time
so that it's ready to start when you need it. The initial status of the
new container is `created`.
The `docker create` command shares most of its options with the `docker run`
command (which performs a `docker create` before starting it). Refer to the
[`docker run` command](run.md) section and the [Docker run reference](../run.md)
for details on the available flags and options.
## Examples
### Create and start a container
The following example creates an interactive container with a pseudo-TTY attached,
then starts the container and attaches to it:
```console
$ docker container create -i -t --name mycontainer alpine
6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
$ docker container start --attach -i mycontainer
/ # echo hello world
hello world
```
The above is the equivalent of a `docker run`:
```console
$ docker run -it --name mycontainer2 alpine
/ # echo hello world
hello world
```
### Initialize volumes
Container volumes are initialized during the `docker create` phase
(i.e., `docker run` too). For example, this allows you to `create` the `data`
volume container, and then use it from another container:
```console
$ docker create -v /data --name data ubuntu
240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57
$ docker run --rm --volumes-from data ubuntu ls -la /data
total 8
drwxr-xr-x 2 root root 4096 Dec 5 04:10 .
drwxr-xr-x 48 root root 4096 Dec 5 04:11 ..
```
Similarly, `create` a host directory bind mounted volume container, which can
then be used from the subsequent container:
```console
$ docker create -v /home/docker:/docker --name docker ubuntu
9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03
$ docker run --rm --volumes-from docker ubuntu ls -la /docker
total 20
drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 .
drwxr-xr-x 48 root root 4096 Dec 5 04:13 ..
-rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history
-rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc
-rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig
drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local
-rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile
drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh
drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker
```

42
docs/reference/commandline/container_diff.md
View File

@ -1,4 +1,4 @@
# container diff # diff
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Inspect changes to files or directories on a container's filesystem Inspect changes to files or directories on a container's filesystem
@ -12,4 +12,42 @@ Inspect changes to files or directories on a container's filesystem
## Description ## Description
See [docker diff](diff.md) for more information. List the changed files and directories in a container᾿s filesystem since the
container was created. Three different types of change are tracked:
| Symbol | Description |
|--------|---------------------------------|
| `A` | A file or directory was added |
| `D` | A file or directory was deleted |
| `C` | A file or directory was changed |
You can use the full or shortened container ID or the container name set using
`docker run --name` option.
## Examples
Inspect the changes to an `nginx` container:
```console
$ docker diff 1fdfd1f54c1b
C /dev
C /dev/console
C /dev/core
C /dev/stdout
C /dev/fd
C /dev/ptmx
C /dev/stderr
C /dev/stdin
C /run
A /run/nginx.pid
C /var/lib/nginx/tmp
A /var/lib/nginx/tmp/client_body
A /var/lib/nginx/tmp/fastcgi
A /var/lib/nginx/tmp/proxy
A /var/lib/nginx/tmp/scgi
A /var/lib/nginx/tmp/uwsgi
C /var/log/nginx
A /var/log/nginx/access.log
A /var/log/nginx/error.log
```

133
docs/reference/commandline/container_exec.md
View File

@ -1,4 +1,4 @@
# container exec # exec
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Execute a command in a running container Execute a command in a running container
@ -9,21 +9,128 @@ Execute a command in a running container
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------------|:---------|:--------|:-------------------------------------------------------| |:------------------------------------------|:---------|:--------|:-------------------------------------------------------|
| `-d`, `--detach` | | | Detached mode: run command in the background | | `-d`, `--detach` | | | Detached mode: run command in the background |
| `--detach-keys` | `string` | | Override the key sequence for detaching a container | | `--detach-keys` | `string` | | Override the key sequence for detaching a container |
| `-e`, `--env` | `list` | | Set environment variables | | [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables |
| `--env-file` | `list` | | Read in a file of environment variables | | `--env-file` | `list` | | Read in a file of environment variables |
| `-i`, `--interactive` | | | Keep STDIN open even if not attached | | `-i`, `--interactive` | | | Keep STDIN open even if not attached |
| `--privileged` | | | Give extended privileges to the command | | `--privileged` | | | Give extended privileges to the command |
| `-t`, `--tty` | | | Allocate a pseudo-TTY | | `-t`, `--tty` | | | Allocate a pseudo-TTY |
| `-u`, `--user` | `string` | | Username or UID (format: `<name\|uid>[:<group\|gid>]`) | | `-u`, `--user` | `string` | | Username or UID (format: `<name\|uid>[:<group\|gid>]`) |
| `-w`, `--workdir` | `string` | | Working directory inside the container | | [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker exec](exec.md) for more information. The `docker exec` command runs a new command in a running container.
The command you specify with `docker exec` only runs while the container's
primary process (`PID 1`) is running, and it isn't restarted if the container
is restarted.
The command runs in the default working directory of the container.
The command must be an executable. A chained or a quoted command doesn't work.
- This works: `docker exec -it my_container sh -c "echo a && echo b"`
- This doesn't work: `docker exec -it my_container "echo a && echo b"`
## Examples
### Run `docker exec` on a running container
First, start a container.
```console
$ docker run --name mycontainer -d -i -t alpine /bin/sh
```
This creates and starts a container named `mycontainer` from an `alpine` image
with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`)
sets the container to run in the background, in detached mode, with a pseudo-TTY
attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which
prevents the `sh` process from exiting immediately.
Next, execute a command on the container.
```console
$ docker exec -d mycontainer touch /tmp/execWorks
```
This creates a new file `/tmp/execWorks` inside the running container
`mycontainer`, in the background.
Next, execute an interactive `sh` shell on the container.
```console
$ docker exec -it mycontainer sh
```
This starts a new shell session in the container `mycontainer`.
### <a name="env"></a> Set environment variables for the exec process (--env, -e)
Next, set environment variables in the current bash session.
The `docker exec` command inherits the environment variables that are set at the
time the container is created. Use the `--env` (or the `-e` shorthand) to
override global environment variables, or to set additional environment
variables for the process started by `docker exec`.
The following example creates a new shell session in the container `mycontainer`,
with environment variables `$VAR_A` set to `1`, and `$VAR_B` set to `2`.
These environment variables are only valid for the `sh` process started by that
`docker exec` command, and aren't available to other processes running inside
the container.
```console
$ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=f64a4851eb71
VAR_A=1
VAR_B=2
HOME=/root
```
### <a name="workdir"></a> Set the working directory for the exec process (--workdir, -w)
By default `docker exec` command runs in the same working directory set when
the container was created.
```console
$ docker exec -it mycontainer pwd
/
```
You can specify an alternative working directory for the command to execute
using the `--workdir` option (or the `-w` shorthand):
```console
$ docker exec -it -w /root mycontainer pwd
/root
```
### Try to run `docker exec` on a paused container
If the container is paused, then the `docker exec` command fails with an error:
```console
$ docker pause mycontainer
mycontainer
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
482efdf39fac alpine "/bin/sh" 17 seconds ago Up 16 seconds (Paused) mycontainer
$ docker exec mycontainer sh
Error response from daemon: Container mycontainer is paused, unpause the container before exec
$ echo $?
1
```

22
docs/reference/commandline/container_export.md
View File

@ -1,4 +1,4 @@
# container export # export
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Export a container's filesystem as a tar archive Export a container's filesystem as a tar archive
@ -18,4 +18,22 @@ Export a container's filesystem as a tar archive
## Description ## Description
See [docker export](export.md) for more information. The `docker export` command doesn't export the contents of volumes associated
with the container. If a volume is mounted on top of an existing directory in
the container, `docker export` exports the contents of the underlying
directory, not the contents of the volume.
Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes)
in the user guide for examples on exporting data in a volume.
## Examples
The following commands produce the same result.
```console
$ docker export red_panda > latest.tar
```
```console
$ docker export --output="latest.tar" red_panda
```

63
docs/reference/commandline/container_kill.md
View File

@ -1,4 +1,4 @@
# container kill # kill
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Kill one or more running containers Kill one or more running containers
@ -9,13 +9,66 @@ Kill one or more running containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:-----------------|:---------|:--------|:--------------------------------| |:---------------------------------------|:---------|:--------|:--------------------------------|
| `-s`, `--signal` | `string` | | Signal to send to the container | | [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker kill](kill.md) for more information. The `docker kill` subcommand kills one or more containers. The main process
inside the container is sent `SIGKILL` signal (default), or the signal that is
specified with the `--signal` option. You can reference a container by its
ID, ID-prefix, or name.
The `--signal` flag sets the system call signal that is sent to the container.
This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGINT`,
or an unsigned number that matches a position in the kernel's syscall table,
for instance `2`.
While the default (`SIGKILL`) signal will terminate the container, the signal
set through `--signal` may be non-terminal, depending on the container's main
process. For example, the `SIGHUP` signal in most cases will be non-terminal,
and the container will continue running after receiving the signal.
> **Note**
>
> `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of
> `/bin/sh -c`, which does not pass signals. This means that the executable is
> not the container’s PID 1 and does not receive Unix signals.
## Examples
### Send a KILL signal to a container
The following example sends the default `SIGKILL` signal to the container named
`my_container`:
```console
$ docker kill my_container
```
### <a name="signal"></a> Send a custom signal to a container (--signal)
The following example sends a `SIGHUP` signal to the container named
`my_container`:
```console
$ docker kill --signal=SIGHUP my_container
```
You can specify a custom signal either by _name_, or _number_. The `SIG` prefix
is optional, so the following examples are equivalent:
```console
$ docker kill --signal=SIGHUP my_container
$ docker kill --signal=HUP my_container
$ docker kill --signal=1 my_container
```
Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html)
man-page for a list of standard Linux signals.

53
docs/reference/commandline/container_logs.md
View File

@ -1,4 +1,4 @@
# container logs # logs
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Fetch the logs of a container Fetch the logs of a container
@ -16,11 +16,58 @@ Fetch the logs of a container
| `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | | `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
| `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs | | `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs |
| `-t`, `--timestamps` | | | Show timestamps | | `-t`, `--timestamps` | | | Show timestamps |
| `--until` | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | | [`--until`](#until) | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker logs](logs.md) for more information. The `docker logs` command batch-retrieves logs present at the time of execution.
For more information about selecting and configuring logging drivers, refer to
[Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/).
The `docker logs --follow` command will continue streaming the new output from
the container's `STDOUT` and `STDERR`.
Passing a negative number or a non-integer to `--tail` is invalid and the
value is set to `all` in that case.
The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://pkg.go.dev/time#RFC3339Nano)
, for example `2014-09-16T06:17:46.000000000Z`, to each
log entry. To ensure that the timestamps are aligned the
nano-second part of the timestamp will be padded with zero when necessary.
The `docker logs --details` command will add on extra attributes, such as
environment variables and labels, provided to `--log-opt` when creating the
container.
The `--since` option shows only the container logs generated after
a given date. You can specify the date as an RFC 3339 date, a UNIX
timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date
format you may also use RFC3339Nano, `2006-01-02T15:04:05`,
`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
timezone on the client 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. You can combine the
`--since` option with either or both of the `--follow` or `--tail` options.
## Examples
### <a name="until"></a> Retrieve logs until a specific point in time (--until)
In order to retrieve logs before a specific point in time, run:
```console
$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
$ date
Tue 14 Nov 2017 16:40:00 CET
$ docker logs -f --until=2s test
Tue 14 Nov 2017 16:40:00 CET
Tue 14 Nov 2017 16:40:01 CET
Tue 14 Nov 2017 16:40:02 CET
```

446
docs/reference/commandline/container_ls.md
View File

@ -1,4 +1,4 @@
# container ls # ps
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
List containers List containers
@ -9,20 +9,440 @@ List containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-a`, `--all` | | | Show all containers (default shows just running) | | [`-a`](#all), [`--all`](#all) | | | Show all containers (default shows just running) |
| `-f`, `--filter` | `filter` | | Filter output based on conditions provided | | [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
| `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) | | `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) |
| `-l`, `--latest` | | | Show the latest created container (includes all states) | | `-l`, `--latest` | | | Show the latest created container (includes all states) |
| `--no-trunc` | | | Don't truncate output | | [`--no-trunc`](#no-trunc) | | | Don't truncate output |
| `-q`, `--quiet` | | | Only display container IDs | | `-q`, `--quiet` | | | Only display container IDs |
| `-s`, `--size` | | | Display total file sizes | | [`-s`](#size), [`--size`](#size) | | | Display total file sizes |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Examples
See [docker ps](ps.md) for more information. ### <a name="no-trunc"></a> Do not truncate output (--no-trunc)
Running `docker ps --no-trunc` showing 2 linked containers.
```console
$ docker ps --no-trunc
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ca5534a51dd04bbcebe9b23ba05f389466cf0c190f1f8f182d7eea92a9671d00 ubuntu:22.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp
9ca9747b233100676a48cc7806131586213fa5dab86dd1972d6a8732e3a84a4d crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db
```
### <a name="all"></a> Show both running and stopped containers (-a, --all)
The `docker ps` command only shows running containers by default. To see all
containers, use the `--all` (or `-a`) flag:
```console
$ docker ps -a
```
`docker ps` groups exposed ports into a single range if possible. E.g., a
container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in
the `PORTS` column.
### <a name="size"></a> Show disk usage by container (--size)
The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container:
```console
$ docker ps --size
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE
e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB)
00c6131c5e30 telegraf:1.5 "/entrypoint.sh" 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB)
```
* The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container
* The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer.
For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section.
### <a name="filter"></a> Filtering (--filter)
The `--filter` (or `-f`) flag format is a `key=value` pair. If there is more
than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
The currently supported filters are:
| Filter | Description |
|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------|
| `id` | Container's ID |
| `name` | Container's name |
| `label` | An arbitrary string representing either a key or a key-value pair. Expressed as `<key>` or `<key>=<value>` |
| `exited` | An integer representing the container's exit code. Only useful with `--all`. |
| `status` | One of `created`, `restarting`, `running`, `removing`, `paused`, `exited`, or `dead` |
| `ancestor` | Filters containers which share a given image as an ancestor. Expressed as `<image-name>[:<tag>]`, `<image id>`, or `<image@digest>` |
| `before` or `since` | Filters containers created before or after a given container ID or name |
| `volume` | Filters running containers which have mounted a given volume or bind mount. |
| `network` | Filters running containers connected to a given network. |
| `publish` or `expose` | Filters containers which publish or expose a given port. Expressed as `<port>[/<proto>]` or `<startport-endport>/[<proto>]` |
| `health` | Filters containers based on their healthcheck status. One of `starting`, `healthy`, `unhealthy` or `none`. |
| `isolation` | Windows daemon only. One of `default`, `process`, or `hyperv`. |
| `is-task` | Filters containers that are a "task" for a service. Boolean option (`true` or `false`) |
#### label
The `label` filter matches containers based on the presence of a `label` alone or a `label` and a
value.
The following filter matches containers with the `color` label regardless of its value.
```console
$ docker ps --filter "label=color"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley
d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani
```
The following filter matches containers with the `color` label with the `blue` value.
```console
$ docker ps --filter "label=color=blue"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani
```
#### name
The `name` filter matches on all or part of a container's name.
The following filter matches all containers with a name containing the `nostalgic_stallman` string.
```console
$ docker ps --filter "name=nostalgic_stallman"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman
```
You can also filter for a substring in a name as this shows:
```console
$ docker ps --filter "name=nostalgic"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
715ebfcee040 busybox "top" 3 seconds ago Up 1 second i_am_nostalgic
9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman
673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley
```
#### exited
The `exited` filter matches containers by exist status code. For example, to
filter for containers that have exited successfully:
```console
$ docker ps -a --filter 'exited=0'
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey
106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani
48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds
```
#### Filter by exit signal
You can use a filter to locate containers that exited with status of `137`
meaning a `SIGKILL(9)` killed them.
```console
$ docker ps -a --filter 'exited=137'
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski
a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande
```
Any of these events result in a `137` status:
* the `init` process of the container is killed manually
* `docker kill` kills the container
* Docker daemon restarts which kills all running containers
#### status
The `status` filter matches containers by status. The possible values for the container status are:
| Status | Description |
| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created` | A container that has never been started. |
| `running` | A running container, started by either `docker start` or `docker run`. |
| `paused` | A paused container. See `docker pause`. |
| `restarting` | A container which is starting due to the designated restart policy for that container. |
| `exited` | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the `docker stop` command. |
| `removing` | A container which is in the process of being removed. See `docker rm`. |
| `dead` | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. `dead` containers cannot be (re)started, only removed. |
For example, to filter for `running` containers:
```console
$ docker ps --filter status=running
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic
d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top
9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman
```
To filter for `paused` containers:
```console
$ docker ps --filter status=paused
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley
```
#### ancestor
The `ancestor` filter matches containers based on its image or a descendant of
it. The filter supports the following image representation:
- `image`
- `image:tag`
- `image:tag@digest`
- `short-id`
- `full-id`
If you don't specify a `tag`, the `latest` tag is used. For example, to filter
for containers that use the latest `ubuntu` image:
```console
$ docker ps --filter ancestor=ubuntu
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet
82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose
bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath
```
Match containers based on the `ubuntu-c1` image which, in this case, is a child
of `ubuntu`:
```console
$ docker ps --filter ancestor=ubuntu-c1
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
```
Match containers based on the `ubuntu` version `22.04` image:
```console
$ docker ps --filter ancestor=ubuntu:22.04
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose
```
The following matches containers based on the layer `d0e008c6cf02` or an image
that have this layer in its layer stack.
```console
$ docker ps --filter ancestor=d0e008c6cf02
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose
```
#### Create time
##### before
The `before` filter shows only containers created before the container with
a given ID or name. For example, having these containers created:
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky
4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat
```
Filtering with `before` would give:
```console
$ docker ps -f before=9c3527ed70ce
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat
```
##### since
The `since` filter shows only containers created since the container with a given
ID or name. For example, with the same containers as in `before` filter:
```console
$ docker ps -f since=6e63f6ff38b0
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky
4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton
```
#### volume
The `volume` filter shows only containers that mount a specific volume or have
a volume mounted in a specific path:
```console
$ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}"
CONTAINER ID MOUNTS
9c3527ed70ce remote-volume
$ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}"
CONTAINER ID MOUNTS
9c3527ed70ce remote-volume
```
#### network
The `network` filter shows only containers that are connected to a network with
a given name or ID.
The following filter matches all containers that are connected to a network
with a name containing `net1`.
```console
$ docker run -d --net=net1 --name=test1 ubuntu top
$ docker run -d --net=net2 --name=test2 ubuntu top
$ docker ps --filter network=net1
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1
```
The network filter matches on both the network's name and ID. The following
example shows all containers that are attached to the `net1` network, using
the network ID as a filter:
```console
$ docker network inspect --format "{{.ID}}" net1
8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5
$ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1
```
#### publish and expose
The `publish` and `expose` filters show only containers that have published or exposed port with a given port
number, port range, and/or protocol. The default protocol is `tcp` when not specified.
The following filter matches all containers that have published port of 80:
```console
$ docker run -d --publish=80 busybox top
$ docker run -d --expose=8080 busybox top
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy
fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen
$ 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
```
The following filter matches all containers that have exposed TCP port in the range of `8000-8080`:
```console
$ 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
```
The following filter matches all containers that have exposed UDP port `80`:
```console
$ docker ps --filter publish=80/udp
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) pretty-prints container output using a Go
template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|:--------------|:------------------------------------------------------------------------------------------------|
| `.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. |
| `.State` | Container status (for example; "created", "running", "exited"). |
| `.Status` | Container status with details about duration and health-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 `'{{.Label "com.docker.swarm.cpu"}}'` |
| `.Mounts` | Names of the volumes mounted in this container. |
| `.Networks` | Names of the networks attached to this container. |
When using the `--format` option, the `ps` command will either output the data
exactly as the template declares or, when using the `table` directive, includes
column headers as well.
The following example uses a template without headers and outputs the `ID` and
`Command` entries separated by a colon (`:`) for all running containers:
```console
$ docker ps --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
```
To list all running containers with their labels in a table format you can use:
```console
$ docker ps --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
```
To list all running containers in JSON format, use the `json` directive:
```console
$ docker ps --format json
{"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"}
```

23
docs/reference/commandline/container_pause.md
View File

@ -1,4 +1,4 @@
# container pause # pause
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Pause all processes within one or more containers Pause all processes within one or more containers
@ -12,4 +12,23 @@ Pause all processes within one or more containers
## Description ## Description
See [docker pause](pause.md) for more information. The `docker pause` command suspends all processes in the specified containers.
On Linux, this uses the freezer cgroup. Traditionally, when suspending a process
the `SIGSTOP` signal is used, which is observable by the process being suspended.
With the freezer cgroup the process is unaware, and unable to capture,
that it is being suspended, and subsequently resumed. On Windows, only Hyper-V
containers can be paused.
See the
[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
for further details.
## Examples
```console
$ docker pause my_container
```
## Related commands
* [unpause](unpause.md)

33
docs/reference/commandline/container_port.md
View File

@ -1,4 +1,4 @@
# container port # port
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
List port mappings or a specific mapping for the container List port mappings or a specific mapping for the container
@ -10,6 +10,33 @@ List port mappings or a specific mapping for the container
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Examples
See [docker port](port.md) for more information. ### Show all mapped ports
You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or
just a specific mapping:
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test
$ docker port test
7890/tcp -> 0.0.0.0:4321
9876/tcp -> 0.0.0.0:1234
$ docker port test 7890/tcp
0.0.0.0:4321
$ docker port test 7890/udp
2014/06/24 11:53:36 Error: No public port '7890/udp' published for test
$ docker port test 7890
0.0.0.0:4321
```

10
docs/reference/commandline/container_rename.md
View File

@ -1,4 +1,4 @@
# container rename # rename
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Rename a container Rename a container
@ -12,4 +12,10 @@ Rename a container
## Description ## Description
See [docker rename](rename.md) for more information. The `docker rename` command renames a container.
## Examples
```console
$ docker rename my_container my_new_container
```

8
docs/reference/commandline/container_restart.md
View File

@ -1,4 +1,4 @@
# container restart # restart
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Restart one or more containers Restart one or more containers
@ -17,6 +17,8 @@ Restart one or more containers
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Examples
See [docker restart](restart.md) for more information. ```console
$ docker restart my_container
```

103
docs/reference/commandline/container_rm.md
View File

@ -1,4 +1,4 @@
# container rm # rm
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Remove one or more containers Remove one or more containers
@ -9,15 +9,102 @@ Remove one or more containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:------------------|:-----|:--------|:--------------------------------------------------------| |:------------------------------------------|:-----|:--------|:--------------------------------------------------------|
| `-f`, `--force` | | | Force the removal of a running container (uses SIGKILL) | | [`-f`](#force), [`--force`](#force) | | | Force the removal of a running container (uses SIGKILL) |
| `-l`, `--link` | | | Remove the specified link | | [`-l`](#link), [`--link`](#link) | | | Remove the specified link |
| `-v`, `--volumes` | | | Remove anonymous volumes associated with the container | | [`-v`](#volumes), [`--volumes`](#volumes) | | | Remove anonymous volumes associated with the container |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Examples
See [docker rm](rm.md) for more information. ### Remove a container
This removes the container referenced under the link `/redis`.
```console
$ docker rm /redis
/redis
```
### <a name="link"></a> Remove a link specified with `--link` on the default bridge network (--link)
This removes the underlying link between `/webapp` and the `/redis`
containers on the default bridge network, removing all network communication
between the two containers. This does not apply when `--link` is used with
user-specified networks.
```console
$ docker rm --link /webapp/redis
/webapp/redis
```
### <a name="force"></a> Force-remove a running container (--force)
This command force-removes a running container.
```console
$ docker rm --force redis
redis
```
The main process inside the container referenced under the link `redis` will receive
`SIGKILL`, then the container will be removed.
### Remove all stopped containers
Use the [`docker container prune`](container_prune.md) command to remove all
stopped containers, or refer to the [`docker system prune`](system_prune.md)
command to remove unused containers in addition to other Docker resources, such
as (unused) images and networks.
Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to
generate a list of container IDs to remove, and use that list as argument for
the `docker rm` command.
Combining commands can be more flexible, but is less portable as it depends
on features provided by the shell, and the exact syntax may differ depending on
what shell is used. To use this approach on Windows, consider using PowerShell
or Bash.
The example below uses `docker ps -q` to print the IDs of all containers that
have exited (`--filter status=exited`), and removes those containers with
the `docker rm` command:
```console
$ docker rm $(docker ps --filter status=exited -q)
```
Or, using the `xargs` Linux utility:
```console
$ docker ps --filter status=exited -q | xargs docker rm
```
### <a name="volumes"></a> Remove a container and its volumes (-v, --volumes)
```console
$ docker rm --volumes redis
redis
```
This command removes the container and any volumes associated with it.
Note that if a volume was specified with a name, it will not be removed.
### Remove a container and selectively remove volumes
```console
$ docker create -v awesome:/foo -v /bar --name hello redis
hello
$ docker rm -v hello
```
In this example, the volume for `/foo` remains intact, but the volume for
`/bar` is removed. The same behavior holds for volumes inherited with
`--volumes-from`.

1559
docs/reference/commandline/container_run.md
View File

File diff suppressed because it is too large Load Diff

8
docs/reference/commandline/container_start.md
View File

@ -1,4 +1,4 @@
# container start # start
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Start one or more stopped containers Start one or more stopped containers
@ -20,6 +20,8 @@ Start one or more stopped containers
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Examples
See [docker start](start.md) for more information. ```console
$ docker start my_container
```

181
docs/reference/commandline/container_stats.md
View File

@ -1,4 +1,4 @@
# container stats # stats
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Display a live stream of container(s) resource usage statistics Display a live stream of container(s) resource usage statistics
@ -9,16 +9,181 @@ Display a live stream of container(s) resource usage statistics
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:--------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-a`, `--all` | | | Show all containers (default shows just running) | | `-a`, `--all` | | | Show all containers (default shows just running) |
| `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `--no-stream` | | | Disable streaming stats and only pull the first result | | `--no-stream` | | | Disable streaming stats and only pull the first result |
| `--no-trunc` | | | Do not truncate output | | `--no-trunc` | | | Do not truncate output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker stats](stats.md) for more information. The `docker stats` command returns a live data stream for running containers. To
limit data to one or more specific containers, specify a list of container names
or ids separated by a space. You can specify a stopped container but stopped
containers do not return any data.
If you need more detailed information about a container's resource usage, use
the `/containers/(id)/stats` API endpoint.
> **Note**
>
> On Linux, the Docker CLI reports memory usage by subtracting cache usage from
> the total memory usage. The API does not perform such a calculation but rather
> provides the total memory usage and the amount from the cache so that clients
> can use the data as needed. The cache usage is defined as the value of
> `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts.
>
> On Docker 19.03 and older, the cache usage was defined as the value of `cache`
> field. On cgroup v2 hosts, the cache usage is defined as the value of
> `inactive_file` field.
> **Note**
>
> The `PIDS` column contains the number of processes and kernel threads created
> by that container. Threads is the term used by Linux kernel. Other equivalent
> terms are "lightweight process" or "kernel task", etc. A large number in the
> `PIDS` column combined with a small number of processes (as reported by `ps`
> or `top`) may indicate that something in the container is creating many threads.
## Examples
Running `docker stats` on all running containers against a Linux daemon.
```console
$ docker stats
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9
67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2
e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1
4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2
```
If you don't [specify a format string using `--format`](#format), the
following columns are shown.
| Column name | Description |
|---------------------------|-----------------------------------------------------------------------------------------------|
| `CONTAINER ID` and `Name` | the ID and name of the container |
| `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using |
| `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use |
| `NET I/O` | The amount of data the container has received and sent over its network interface |
| `BLOCK I/O` | The amount of data the container has written to and read from block devices on the host |
| `PIDs` | the number of processes or threads the container has created |
Running `docker stats` on multiple containers by name and id against a Linux daemon.
```console
$ docker stats awesome_brattain 67b2525d8ad1
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9
67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2
```
Running `docker stats` on container with name `nginx` and getting output in `json` format.
```console
$ docker stats nginx --no-stream --format "{{ json . }}"
{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"}
```
Running `docker stats` with customized format on all (running and stopped) containers.
```console
$ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 humble_visvesvaraya big_heisenberg
CONTAINER CPU % MEM USAGE / LIMIT
fervent_panini 0.00% 56KiB / 15.57GiB
5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB
humble_visvesvaraya 0.00% 0B / 0B
big_heisenberg 0.00% 0B / 0B
```
`humble_visvesvaraya` and `big_heisenberg` are stopped containers in the above example.
Running `docker stats` on all running containers against a Windows daemon.
```powershell
PS E:\> docker stats
CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O
09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB
9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB
3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB
```
Running `docker stats` on multiple containers by name and id against a Windows daemon.
```powershell
PS E:\> docker ps -a
CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES
3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky
9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson
09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley
PS E:\> docker stats 3f214c61ad1d mad_wilson
CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O
3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB
9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) pretty prints container output
using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|--------------|----------------------------------------------|
| `.Container` | Container name or ID (user input) |
| `.Name` | Container name |
| `.ID` | Container ID |
| `.CPUPerc` | CPU percentage |
| `.MemUsage` | Memory usage |
| `.NetIO` | Network IO |
| `.BlockIO` | Block IO |
| `.MemPerc` | Memory percentage (Not available on Windows) |
| `.PIDs` | Number of PIDs (Not available on Windows) |
When using the `--format` option, the `stats` command either
outputs the data exactly as the template declares or, when using the
`table` directive, includes column headers as well.
The following example uses a template without headers and outputs the
`Container` and `CPUPerc` entries separated by a colon (`:`) for all images:
```console
$ docker stats --format "{{.Container}}: {{.CPUPerc}}"
09d3bb5b1604: 6.61%
9db7aa4d986d: 9.19%
3f214c61ad1d: 0.00%
```
To list all containers statistics with their name, CPU percentage and memory
usage in a table format you can use:
```console
$ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
CONTAINER CPU % PRIV WORKING SET
1285939c1fd3 0.07% 796 KiB / 64 MiB
9c76f7834ae2 0.07% 2.746 MiB / 64 MiB
d1ea048f04e4 0.03% 4.583 MiB / 64 MiB
```
The default format is as follows:
On Linux:
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}"
On Windows:
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"

13
docs/reference/commandline/container_stop.md
View File

@ -1,4 +1,4 @@
# container stop # stop
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Stop one or more running containers Stop one or more running containers
@ -19,4 +19,13 @@ Stop one or more running containers
## Description ## Description
See [docker stop](stop.md) for more information. The main process inside the container will receive `SIGTERM`, and after a grace
period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL`
instruction in the container's Dockerfile, or the `--stop-signal` option to
`docker run`.
## Examples
```console
$ docker stop my_container
```

6
docs/reference/commandline/container_top.md
View File

@ -1,4 +1,4 @@
# container top # top
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Display the running processes of a container Display the running processes of a container
@ -9,7 +9,3 @@ Display the running processes of a container
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
See [docker top](top.md) for more information.

20
docs/reference/commandline/container_unpause.md
View File

@ -1,4 +1,4 @@
# container unpause # unpause
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Unpause all processes within one or more containers Unpause all processes within one or more containers
@ -12,4 +12,20 @@ Unpause all processes within one or more containers
## Description ## Description
See [docker unpause](unpause.md) for more information. The `docker unpause` command un-suspends all processes in the specified containers.
On Linux, it does this using the freezer cgroup.
See the
[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
for further details.
## Examples
```console
$ docker unpause my_container
my_container
```
## Related commands
* [pause](pause.md)

126
docs/reference/commandline/container_update.md
View File

@ -1,4 +1,4 @@
# container update ## update
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Update configuration of one or more containers Update configuration of one or more containers
@ -9,26 +9,116 @@ Update configuration of one or more containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:-----------------------|:----------|:--------|:-----------------------------------------------------------------------------| |:---------------------------------------------------|:----------|:--------|:-----------------------------------------------------------------------------|
| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | | `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | | `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period |
| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | | `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota |
| `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds | | `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds |
| `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds | | `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds |
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | | [`-c`](#cpu-shares), [`--cpu-shares`](#cpu-shares) | `int64` | `0` | CPU shares (relative weight) |
| `--cpus` | `decimal` | | Number of CPUs | | `--cpus` | `decimal` | | Number of CPUs |
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | | `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | | `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
| `-m`, `--memory` | `bytes` | `0` | Memory limit | | [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit |
| `--memory-reservation` | `bytes` | `0` | Memory soft limit | | `--memory-reservation` | `bytes` | `0` | Memory soft limit |
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | | `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | | `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) |
| `--restart` | `string` | | Restart policy to apply when a container exits | | [`--restart`](#restart) | `string` | | Restart policy to apply when a container exits |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker update](update.md) for more information. The `docker update` command dynamically updates container configuration.
You can use this command to prevent containers from consuming too many
resources from their Docker host. With a single command, you can place
limits on a single container or on many. To specify more than one container,
provide space-separated list of container names or IDs.
With the exception of the `--kernel-memory` option, you can specify these
options on a running or a stopped container. On kernel version older than
4.6, you can only update `--kernel-memory` on a stopped container or on
a running container with kernel memory initialized.
> **Warning**
>
> The `docker update` and `docker container update` commands are not supported
> for Windows containers.
{ .warning }
## Examples
The following sections illustrate ways to use this command.
### <a name="cpu-shares"></a> Update a container's cpu-shares (--cpu-shares)
To limit a container's cpu-shares to 512, first identify the container
name or ID. You can use `docker ps` to find these values. You can also
use the ID returned from the `docker run` command. Then, do the following:
```console
$ docker update --cpu-shares 512 abebf7571666
```
### <a name="memory"></a> Update a container with cpu-shares and memory (-m, --memory)
To update multiple resource configurations for multiple containers:
```console
$ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse
```
### <a name="kernel-memory"></a> Update a container's kernel memory constraints (--kernel-memory)
You can update a container's kernel memory limit using the `--kernel-memory`
option. On kernel version older than 4.6, this option can be updated on a
running container only if the container was started with `--kernel-memory`.
If the container was started without `--kernel-memory` you need to stop
the container before updating kernel memory.
> **Note**
>
> The `--kernel-memory` option has been deprecated since Docker 20.10.
For example, if you started a container with this command:
```console
$ docker run -dit --name test --kernel-memory 50M ubuntu bash
```
You can update kernel memory while the container is running:
```console
$ docker update --kernel-memory 80M test
```
If you started a container without kernel memory initialized:
```console
$ docker run -dit --name test2 --memory 300M ubuntu bash
```
Update kernel memory of running container `test2` will fail. You need to stop
the container before updating the `--kernel-memory` setting. The next time you
start it, the container uses the new value.
Kernel version newer than (include) 4.6 does not have this limitation, you
can use `--kernel-memory` the same way as other options.
### <a name="restart"></a> Update a container's restart policy (--restart)
You can change a container's restart policy on a running container. The new
restart policy takes effect instantly after you run `docker update` on a
container.
To update restart policy for one or more containers:
```console
$ docker update --restart=on-failure:3 abebf7571666 hopeful_morse
```
Note that if the container is started with `--rm` flag, you cannot update the restart
policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the
container.

37
docs/reference/commandline/container_wait.md
View File

@ -1,4 +1,4 @@
# container wait # wait
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Block until one or more containers stop, then print their exit codes Block until one or more containers stop, then print their exit codes
@ -10,6 +10,37 @@ Block until one or more containers stop, then print their exit codes
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description > **Note**
>
> `docker wait` returns `0` when run against a container which had already
> exited before the `docker wait` command was run.
See [docker wait](wait.md) for more information. ## Examples
Start a container in the background.
```console
$ docker run -dit --name=my_container ubuntu bash
```
Run `docker wait`, which should block until the container exits.
```console
$ docker wait my_container
```
In another terminal, stop the first container. The `docker wait` command above
returns the exit code.
```console
$ docker stop my_container
```
This is the same `docker wait` command from above, but it now exits, returning
`0`.
```console
$ docker wait my_container
0
```

108
docs/reference/commandline/cp.md
View File

@ -1,4 +1,4 @@
# cp # docker cp
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Copy files/folders between a container and the local filesystem Copy files/folders between a container and the local filesystem
@ -23,109 +23,3 @@ container source to stdout.
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`.
You can copy from the container's file system to the local machine or the
reverse, from the local filesystem to the container. If `-` is specified for
either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from
`STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container.
The `SRC_PATH` or `DEST_PATH` can be a file or directory.
The `docker cp` command assumes container paths are relative to the container's
`/` (root) directory. This means supplying the initial forward slash is optional;
The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and
`compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can
be an absolute or relative value. The command interprets a local machine's
relative paths as relative to the current working directory where `docker cp` is
run.
The `cp` command behaves like the Unix `cp -a` command in that directories are
copied recursively with permissions preserved if possible. Ownership is set to
the user and primary group at the destination. For example, files copied to a
container are created with `UID:GID` of the root user. Files copied to the local
machine are created with the `UID:GID` of the user which invoked the `docker cp`
command. However, if you specify the `-a` option, `docker cp` sets the ownership
to the user and primary group at the source.
If you specify the `-L` option, `docker cp` follows any symbolic link
in the `SRC_PATH`. `docker cp` doesn't create parent directories for
`DEST_PATH` if they don't exist.
Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
argument of `DEST_PATH`, the behavior is as follows:
- `SRC_PATH` specifies a file
- `DEST_PATH` does not exist
- the file is saved to a file created at `DEST_PATH`
- `DEST_PATH` does not exist and ends with `/`
- Error condition: the destination directory must exist.
- `DEST_PATH` exists and is a file
- the destination is overwritten with the source file's contents
- `DEST_PATH` exists and is a directory
- the file is copied into this directory using the basename from
`SRC_PATH`
- `SRC_PATH` specifies a directory
- `DEST_PATH` does not exist
- `DEST_PATH` is created as a directory and the *contents* of the source
directory are copied into this directory
- `DEST_PATH` exists and is a file
- Error condition: cannot copy a directory to a file
- `DEST_PATH` exists and is a directory
- `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_)
- the source directory is copied into this directory
- `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_)
- the *content* of the source directory is copied into this
directory
The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above
rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
the target, is copied by default. To copy the link target and not the link, specify
the `-L` option.
A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can
also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local
machine, for example `file:name.txt`. If you use a `:` in a local machine path,
you must be explicit with a relative or absolute path, for example:
`/path/to/file:name.txt` or `./file:name.txt`
## Examples
Copy a local file into container
```console
$ docker cp ./some_file CONTAINER:/work
```
Copy files from container to local path
```console
$ docker cp CONTAINER:/var/logs/ /tmp/app_logs
```
Copy a file from container to stdout. Please note `cp` command produces a tar stream
```console
$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR"
```
### Corner cases
It isn't possible to copy certain system files such as resources under
`/proc`, `/sys`, `/dev`, [tmpfs](run.md#tmpfs), and mounts created by
the user in the container. However, you can still copy such files by manually
running `tar` in `docker exec`. Both of the following examples do the same thing
in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):
```console
$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
```
```console
$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH -
```
Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
The command extracts the content of the tar to the `DEST_PATH` in container's
filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as
the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.

85
docs/reference/commandline/create.md
View File

@ -1,4 +1,4 @@
# create # docker create
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Create a new container Create a new container
@ -115,86 +115,3 @@ Create a new container
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker container create` (or shorthand: `docker create`) command creates a
new container from the specified image, without starting it.
When creating a container, the Docker daemon creates a writeable container layer
over the specified image and prepares it for running the specified command. The
container ID is then printed to `STDOUT`. This is similar to `docker run -d`
except the container is never started. You can then use the `docker container start`
(or shorthand: `docker start`) command to start the container at any point.
This is useful when you want to set up a container configuration ahead of time
so that it's ready to start when you need it. The initial status of the
new container is `created`.
The `docker create` command shares most of its options with the `docker run`
command (which performs a `docker create` before starting it). Refer to the
[`docker run` command](run.md) section and the [Docker run reference](../run.md)
for details on the available flags and options.
## Examples
### Create and start a container
The following example creates an interactive container with a pseudo-TTY attached,
then starts the container and attaches to it:
```console
$ docker container create -i -t --name mycontainer alpine
6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
$ docker container start --attach -i mycontainer
/ # echo hello world
hello world
```
The above is the equivalent of a `docker run`:
```console
$ docker run -it --name mycontainer2 alpine
/ # echo hello world
hello world
```
### Initialize volumes
Container volumes are initialized during the `docker create` phase
(i.e., `docker run` too). For example, this allows you to `create` the `data`
volume container, and then use it from another container:
```console
$ docker create -v /data --name data ubuntu
240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57
$ docker run --rm --volumes-from data ubuntu ls -la /data
total 8
drwxr-xr-x 2 root root 4096 Dec 5 04:10 .
drwxr-xr-x 48 root root 4096 Dec 5 04:11 ..
```
Similarly, `create` a host directory bind mounted volume container, which can
then be used from the subsequent container:
```console
$ docker create -v /home/docker:/docker --name docker ubuntu
9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03
$ docker run --rm --volumes-from docker ubuntu ls -la /docker
total 20
drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 .
drwxr-xr-x 48 root root 4096 Dec 5 04:13 ..
-rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history
-rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc
-rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig
drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local
-rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile
drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh
drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker
```

43
docs/reference/commandline/diff.md
View File

@ -1,4 +1,4 @@
# diff # docker diff
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Inspect changes to files or directories on a container's filesystem Inspect changes to files or directories on a container's filesystem
@ -10,44 +10,3 @@ Inspect changes to files or directories on a container's filesystem
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
List the changed files and directories in a container᾿s filesystem since the
container was created. Three different types of change are tracked:
| Symbol | Description |
|--------|---------------------------------|
| `A` | A file or directory was added |
| `D` | A file or directory was deleted |
| `C` | A file or directory was changed |
You can use the full or shortened container ID or the container name set using
`docker run --name` option.
## Examples
Inspect the changes to an `nginx` container:
```console
$ docker diff 1fdfd1f54c1b
C /dev
C /dev/console
C /dev/core
C /dev/stdout
C /dev/fd
C /dev/ptmx
C /dev/stderr
C /dev/stdin
C /run
A /run/nginx.pid
C /var/lib/nginx/tmp
A /var/lib/nginx/tmp/client_body
A /var/lib/nginx/tmp/fastcgi
A /var/lib/nginx/tmp/proxy
A /var/lib/nginx/tmp/scgi
A /var/lib/nginx/tmp/uwsgi
C /var/log/nginx
A /var/log/nginx/access.log
A /var/log/nginx/error.log
```

407
docs/reference/commandline/events.md
View File

@ -1,4 +1,4 @@
# events # docker events
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Get real time events from the server Get real time events from the server
@ -9,406 +9,13 @@ Get real time events from the server
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | | `-f`, `--filter` | `filter` | | Filter output based on conditions provided |
| [`--format`](#format) | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | `--format` | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| [`--since`](#since) | `string` | | Show all events created since timestamp | | `--since` | `string` | | Show all events created since timestamp |
| `--until` | `string` | | Stream events until this timestamp | | `--until` | `string` | | Stream events until this timestamp |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
Use `docker events` to get real-time events from the server. These events differ
per Docker object type. Different event types have different scopes. Local
scoped events are only seen on the node they take place on, and Swarm scoped
events are seen on all managers.
Only the last 1000 log events are returned. You can use filters to further limit
the number of events returned.
### Object types
#### Containers
Docker containers report the following events:
- `attach`
- `commit`
- `copy`
- `create`
- `destroy`
- `detach`
- `die`
- `exec_create`
- `exec_detach`
- `exec_die`
- `exec_start`
- `export`
- `health_status`
- `kill`
- `oom`
- `pause`
- `rename`
- `resize`
- `restart`
- `start`
- `stop`
- `top`
- `unpause`
- `update`
#### Images
Docker images report the following events:
- `delete`
- `import`
- `load`
- `pull`
- `push`
- `save`
- `tag`
- `untag`
#### Plugins
Docker plugins report the following events:
- `enable`
- `disable`
- `install`
- `remove`
#### Volumes
Docker volumes report the following events:
- `create`
- `destroy`
- `mount`
- `unmount`
#### Networks
Docker networks report the following events:
- `create`
- `connect`
- `destroy`
- `disconnect`
- `remove`
#### Daemons
Docker daemons report the following events:
- `reload`
#### Services
Docker services report the following events:
- `create`
- `remove`
- `update`
#### Nodes
Docker nodes report the following events:
- `create`
- `remove`
- `update`
#### Secrets
Docker secrets report the following events:
- `create`
- `remove`
- `update`
#### Configs
Docker configs report the following events:
- `create`
- `remove`
- `update`
### Limiting, filtering, and formatting the output
#### <a name="since"></a> Limit events by time (--since, --until)
The `--since` and `--until` parameters can be Unix timestamps, date formatted
timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
relative to the client machine’s time. If you do not provide the `--since` option,
the command returns only new and/or live events. Supported formats for date
formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`,
`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
timezone on the client 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.
Only the last 1000 log events are returned. You can use filters to further limit
the number of events returned.
#### <a name="filter"></a> Filtering (--filter)
The filtering flag (`-f` or `--filter`) format is of "key=value". If you would
like to use multiple filters, pass multiple flags (e.g.,
`--filter "foo=bar" --filter "bif=baz"`)
Using the same filter multiple times is interpreted as a logical `OR`; for example,
`--filter container=588a23dac085 --filter container=a8f7720b8c22` displays
events for container `588a23dac085` or container `a8f7720b8c22`.
Using multiple filters is interpreted as a logical `AND`; for example,
`--filter container=588a23dac085 --filter event=start` displays events for
container `588a23dac085` and where the event type is `start`.
The currently supported filters are:
- config (`config=<name or id>`)
- container (`container=<name or id>`)
- daemon (`daemon=<name or id>`)
- event (`event=<event action>`)
- image (`image=<repository or tag>`)
- label (`label=<key>` or `label=<key>=<value>`)
- network (`network=<name or id>`)
- node (`node=<id>`)
- plugin (`plugin=<name or id>`)
- scope (`scope=<local or swarm>`)
- secret (`secret=<name or id>`)
- service (`service=<name or id>`)
- type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
- volume (`volume=<name>`)
#### <a name="format"></a> Format the output (--format)
If you specify a format (`--format`), the given template is executed
instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
package describes all the details of the format.
If a format is set to `{{json .}}`, events are streamed in the JSON Lines format.
For information about JSON Lines, see <https://jsonlines.org/>.
## Examples
### Basic example
You'll need two shells for this example.
**Shell 1: Listening for events:**
```console
$ docker events
```
**Shell 2: Start and Stop containers:**
```console
$ docker create --name test alpine:latest top
$ docker start test
$ docker stop test
```
**Shell 1: (Again .. now showing events):**
```console
2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
```
To exit the `docker events` command, use `CTRL+C`.
### Filter events by time
You can filter the output by an absolute timestamp or relative time on the host
machine, using the following different time formats:
```console
$ docker events --since 1483283804
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker events --since '2017-01-05'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker events --since '2013-09-03T15:49:29'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker events --since '10m'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36:05'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
```
### Filter events by criteria
The following commands show several different ways to filter the `docker event`
output.
```console
$ docker events --filter 'event=stop'
2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain)
$ docker events --filter 'image=alpine'
2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner)
2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15)
2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9)
2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner)
2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner)
$ docker events --filter 'container=test'
2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8'
2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9)
2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test)
2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test)
$ docker events --filter 'container=test' --filter 'event=stop'
2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test)
$ docker events --filter 'type=volume'
2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate)
2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local)
2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
$ docker events --filter 'type=network'
2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge)
2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge)
$ docker events --filter 'container=container_1' --filter 'container=container_2'
2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04)
2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04)
2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8)
2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8)
$ docker events --filter 'type=volume'
2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate)
2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local)
2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
$ docker events --filter 'type=network'
2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge)
2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge)
$ docker events --filter 'type=plugin'
2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
$ docker events -f type=service
2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
$ docker events -f type=node
2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown)
$ docker events -f type=secret
2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
$ docker events -f type=config
2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
$ docker events --filter 'scope=swarm'
2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson)
2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret)
```
### Format the output
```console
$ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}'
Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
```
#### Format as JSON
To list events in JSON format, use the `json` directive, which is the same
`--format '{{ json . }}`.
```console
$ docker events --format json
{"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e..
{"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
{"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
```

134
docs/reference/commandline/exec.md
View File

@ -1,4 +1,4 @@
# exec # docker exec
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Execute a command in a running container Execute a command in a running container
@ -9,128 +9,18 @@ Execute a command in a running container
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:------------------------------------------|:---------|:--------|:-------------------------------------------------------| |:----------------------|:---------|:--------|:-------------------------------------------------------|
| `-d`, `--detach` | | | Detached mode: run command in the background | | `-d`, `--detach` | | | Detached mode: run command in the background |
| `--detach-keys` | `string` | | Override the key sequence for detaching a container | | `--detach-keys` | `string` | | Override the key sequence for detaching a container |
| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | | `-e`, `--env` | `list` | | Set environment variables |
| `--env-file` | `list` | | Read in a file of environment variables | | `--env-file` | `list` | | Read in a file of environment variables |
| `-i`, `--interactive` | | | Keep STDIN open even if not attached | | `-i`, `--interactive` | | | Keep STDIN open even if not attached |
| `--privileged` | | | Give extended privileges to the command | | `--privileged` | | | Give extended privileges to the command |
| `-t`, `--tty` | | | Allocate a pseudo-TTY | | `-t`, `--tty` | | | Allocate a pseudo-TTY |
| `-u`, `--user` | `string` | | Username or UID (format: `<name\|uid>[:<group\|gid>]`) | | `-u`, `--user` | `string` | | Username or UID (format: `<name\|uid>[:<group\|gid>]`) |
| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | | `-w`, `--workdir` | `string` | | Working directory inside the container |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker exec` command runs a new command in a running container.
The command you specify with `docker exec` only runs while the container's
primary process (`PID 1`) is running, and it isn't restarted if the container
is restarted.
The command runs in the default working directory of the container.
The command must be an executable. A chained or a quoted command doesn't work.
- This works: `docker exec -it my_container sh -c "echo a && echo b"`
- This doesn't work: `docker exec -it my_container "echo a && echo b"`
## Examples
### Run `docker exec` on a running container
First, start a container.
```console
$ docker run --name mycontainer -d -i -t alpine /bin/sh
```
This creates and starts a container named `mycontainer` from an `alpine` image
with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`)
sets the container to run in the background, in detached mode, with a pseudo-TTY
attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which
prevents the `sh` process from exiting immediately.
Next, execute a command on the container.
```console
$ docker exec -d mycontainer touch /tmp/execWorks
```
This creates a new file `/tmp/execWorks` inside the running container
`mycontainer`, in the background.
Next, execute an interactive `sh` shell on the container.
```console
$ docker exec -it mycontainer sh
```
This starts a new shell session in the container `mycontainer`.
### <a name="env"></a> Set environment variables for the exec process (--env, -e)
Next, set environment variables in the current bash session.
The `docker exec` command inherits the environment variables that are set at the
time the container is created. Use the `--env` (or the `-e` shorthand) to
override global environment variables, or to set additional environment
variables for the process started by `docker exec`.
The following example creates a new shell session in the container `mycontainer`,
with environment variables `$VAR_A` set to `1`, and `$VAR_B` set to `2`.
These environment variables are only valid for the `sh` process started by that
`docker exec` command, and aren't available to other processes running inside
the container.
```console
$ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=f64a4851eb71
VAR_A=1
VAR_B=2
HOME=/root
```
### <a name="workdir"></a> Set the working directory for the exec process (--workdir, -w)
By default `docker exec` command runs in the same working directory set when
the container was created.
```console
$ docker exec -it mycontainer pwd
/
```
You can specify an alternative working directory for the command to execute
using the `--workdir` option (or the `-w` shorthand):
```console
$ docker exec -it -w /root mycontainer pwd
/root
```
### Try to run `docker exec` on a paused container
If the container is paused, then the `docker exec` command fails with an error:
```console
$ docker pause mycontainer
mycontainer
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
482efdf39fac alpine "/bin/sh" 17 seconds ago Up 16 seconds (Paused) mycontainer
$ docker exec mycontainer sh
Error response from daemon: Container mycontainer is paused, unpause the container before exec
$ echo $?
1
```

23
docs/reference/commandline/export.md
View File

@ -1,4 +1,4 @@
# export # docker export
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Export a container's filesystem as a tar archive Export a container's filesystem as a tar archive
@ -16,24 +16,3 @@ Export a container's filesystem as a tar archive
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker export` command doesn't export the contents of volumes associated
with the container. If a volume is mounted on top of an existing directory in
the container, `docker export` exports the contents of the underlying
directory, not the contents of the volume.
Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes)
in the user guide for examples on exporting data in a volume.
## Examples
The following commands produce the same result.
```console
$ docker export red_panda > latest.tar
```
```console
$ docker export --output="latest.tar" red_panda
```

71
docs/reference/commandline/history.md
View File

@ -1,4 +1,4 @@
# history # docker history
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Show the history of an image Show the history of an image
@ -9,70 +9,13 @@ Show the history of an image
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `-H`, `--human` | | | Print sizes and dates in human readable format | | `-H`, `--human` | | | Print sizes and dates in human readable format |
| `--no-trunc` | | | Don't truncate output | | `--no-trunc` | | | Don't truncate output |
| `-q`, `--quiet` | | | Only show image IDs | | `-q`, `--quiet` | | | Only show image IDs |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Examples
To see how the `docker:latest` image was built:
```console
$ docker history docker
IMAGE CREATED CREATED BY SIZE COMMENT
3e23a5875458 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B
8578938dd170 8 days ago /bin/sh -c dpkg-reconfigure locales && loc 1.245 MB
be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get install 338.3 MB
4b137612be55 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB
750d58736b4b 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi <ad 0 B
511136ea3c5a 9 months ago 0 B Imported from -
```
To see how the `docker:apache` image was added to a container's base image:
```console
$ docker history docker:scm
IMAGE CREATED CREATED BY SIZE COMMENT
2ac9d1098bf1 3 months ago /bin/bash 241.4 MB Added Apache to Fedora base image
88b42ffd1f7c 5 months ago /bin/sh -c #(nop) ADD file:1fd8d7f9f6557cafc7 373.7 MB
c69cab00d6ef 5 months ago /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar 0 B
511136ea3c5a 19 months ago 0 B Imported from -
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) will pretty-prints history output
using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|-----------------|-----------------------------------------------------------------------------------------------------------|
| `.ID` | Image ID |
| `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created |
| `.CreatedAt` | Timestamp of when image was created |
| `.CreatedBy` | Command that was used to create the image |
| `.Size` | Image disk size |
| `.Comment` | Comment for image |
When using the `--format` option, the `history` command either
outputs the data exactly as the template declares or, when using the
`table` directive, includes column headers as well.
The following example uses a template without headers and outputs the
`ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox`
image:
```console
$ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox
f6e427c148a7: 4 weeks ago
<missing>: 4 weeks ago
```

780
docs/reference/commandline/image_build.md
View File

@ -1,4 +1,4 @@
# image build # build
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Build an image from a Dockerfile Build an image from a Dockerfile
@ -9,42 +9,754 @@ Build an image from a Dockerfile
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:--------------------------|:--------------|:----------|:------------------------------------------------------------------| |:------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) | | [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
| `--build-arg` | `list` | | Set build-time variables | | [`--build-arg`](#build-arg) | `list` | | Set build-time variables |
| `--cache-from` | `stringSlice` | | Images to consider as cache sources | | [`--cache-from`](#cache-from) | `stringSlice` | | Images to consider as cache sources |
| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build | | [`--cgroup-parent`](#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
| `--compress` | | | Compress the build context using gzip | | `--compress` | | | Compress the build context using gzip |
| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period | | `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota | | `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | | `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | | `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | | `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
| `--disable-content-trust` | | | Skip image verification | | `--disable-content-trust` | | | Skip image verification |
| `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) | | [`-f`](#file), [`--file`](#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
| `--force-rm` | | | Always remove intermediate containers | | `--force-rm` | | | Always remove intermediate containers |
| `--iidfile` | `string` | | Write the image ID to the file | | `--iidfile` | `string` | | Write the image ID to the file |
| `--isolation` | `string` | | Container isolation technology | | [`--isolation`](#isolation) | `string` | | Container isolation technology |
| `--label` | `list` | | Set metadata for an image | | `--label` | `list` | | Set metadata for an image |
| `-m`, `--memory` | `bytes` | `0` | Memory limit | | `-m`, `--memory` | `bytes` | `0` | Memory limit |
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | | `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build | | [`--network`](#network) | `string` | `default` | Set the networking mode for the RUN instructions during build |
| `--no-cache` | | | Do not use cache when building the image | | `--no-cache` | | | Do not use cache when building the image |
| `--platform` | `string` | | Set platform if server is multi-platform capable | | `--platform` | `string` | | Set platform if server is multi-platform capable |
| `--pull` | | | Always attempt to pull a newer version of the image | | `--pull` | | | Always attempt to pull a newer version of the image |
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | | `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
| `--rm` | | | Remove intermediate containers after a successful build | | `--rm` | | | Remove intermediate containers after a successful build |
| `--security-opt` | `stringSlice` | | Security options | | [`--security-opt`](#security-opt) | `stringSlice` | | Security options |
| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | | `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
| `--squash` | | | Squash newly built layers into a single new layer | | [`--squash`](#squash) | | | Squash newly built layers into a single new layer |
| `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format | | [`-t`](#tag), [`--tag`](#tag) | `list` | | Name and optionally a tag in the `name:tag` format |
| `--target` | `string` | | Set the target build stage to build. | | [`--target`](#target) | `string` | | Set the target build stage to build. |
| `--ulimit` | `ulimit` | | Ulimit options | | [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker build](build.md) for more information. The `docker build` command builds Docker images from a Dockerfile and a
"context". A build's context is the set of files located in the specified
`PATH` or `URL`. The build process can refer to any of the files in the
context. For example, your build can use a [*COPY*](https://docs.docker.com/engine/reference/builder/#copy)
instruction to reference a file in the context.
The `URL` parameter can refer to three kinds of resources: Git repositories,
pre-packaged tarball contexts, and plain text files.
### Git repositories
When the `URL` parameter points to the location of a Git repository, the
repository acts as the build context. The system recursively fetches the
repository and its submodules. The commit history isn't preserved. A
repository is first pulled into a temporary directory on your local host. After
that succeeds, the command sends the directory to the Docker daemon as the context.
Local copy gives you the ability to access private repositories using local
user credentials, VPNs, and so forth.
> **Note**
>
> If the `URL` parameter contains a fragment the system recursively clones
> the repository and its submodules using a `git clone --recursive` command.
Git URLs accept context configuration in their fragment section, separated by a
colon (`:`). The first part represents the reference that Git checks out,
and can be either a branch, a tag, or a remote reference. The second part
represents a subdirectory inside the repository used as a build
context.
For example, run this command to use a directory called `docker` in the branch
`container`:
```console
$ docker build https://github.com/docker/rootfs.git#container:docker
```
The following table represents all the valid suffixes with their build
contexts:
| Build Syntax Suffix | Commit Used | Build Context Used |
|--------------------------------|-----------------------|--------------------|
| `myrepo.git` | `refs/heads/master` | `/` |
| `myrepo.git#mytag` | `refs/tags/mytag` | `/` |
| `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` |
| `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` |
| `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` |
| `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` |
| `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` |
| `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` |
### Tarball contexts
If you pass a URL to a remote tarball, the command sends the URL itself to the
daemon:
```console
$ docker build http://server/context.tar.gz
```
The host running the Docker daemon performs the download operation,
which isn't necessarily the same host that issued the build command.
The Docker daemon fetches `context.tar.gz` and uses it as the
build context. Tarball contexts must be tar archives conforming to the standard
`tar` Unix format and can be compressed with any one of the `xz`, `bzip2`,
`gzip` or `identity` (no compression) formats.
### Text files
Instead of specifying a context, you can pass a single `Dockerfile` in the
`URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`:
```console
$ docker build - < Dockerfile
```
With PowerShell on Windows, you run:
```powershell
Get-Content Dockerfile | docker build -
```
If you use `STDIN` or specify a `URL` pointing to a plain text file, the daemon
places the contents into a `Dockerfile`, and ignores any `-f`, `--file`
option. In this scenario, there is no context.
By default the `docker build` command looks for a `Dockerfile` at the root
of the build context. The `-f`, `--file`, option lets you specify the path to
an alternative file to use instead. This is useful in cases that use the same
set of files for multiple builds. The path must be to a file within the
build context. Relative path are interpreted as relative to the root of the
context.
In most cases, it's best to put each Dockerfile in an empty directory. Then,
add to that directory only the files needed for building the Dockerfile. To
increase the build's performance, you can exclude files and directories by
adding a `.dockerignore` file to that directory as well. For information on
creating one, see the [.dockerignore file](https://docs.docker.com/engine/reference/builder/#dockerignore-file).
If the Docker client loses connection to the daemon, it cancels the build.
This happens if you interrupt the Docker client with `CTRL-c` or if the Docker
client is killed for any reason. If the build initiated a pull which is still
running at the time the build is cancelled, the client also cancels the pull.
## Return code
Successful builds return exit code `0`. When the build fails, the command
returns a non-zero exit code and prints an error message to `STDERR`:
```console
$ docker build -t fail .
Sending build context to Docker daemon 2.048 kB
Sending build context to Docker daemon
Step 1/3 : FROM busybox
---> 4986bf8c1536
Step 2/3 : RUN exit 13
---> Running in e26670ec7a0a
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
$ echo $?
1
```
See also:
[*Dockerfile Reference*](https://docs.docker.com/engine/reference/builder/).
## Examples
### Build with PATH
```console
$ docker build .
Uploading context 10240 bytes
Step 1/3 : FROM busybox
Pulling repository busybox
---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
Step 2/3 : RUN ls -lh /
---> Running in 9c9e81692ae9
total 24
drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin
drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev
drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib
lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib
dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc
lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin
dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys
drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp
drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr
---> b35f4035db3f
Step 3/3 : CMD echo Hello world
---> Running in 02071fceb21b
---> f52f38b7823e
Successfully built f52f38b7823e
Removing intermediate container 9c9e81692ae9
Removing intermediate container 02071fceb21b
```
This example specifies that the `PATH` is `.`, and so `tar`s all the files in the
local directory and sends them to the Docker daemon. The `PATH` specifies
where to find the files for the "context" of the build on the Docker daemon.
Remember that the daemon could be running on a remote machine and that no
parsing of the Dockerfile happens at the client side (where you're running
`docker build`). That means that all the files at `PATH` are sent, not just
the ones listed to [`ADD`](https://docs.docker.com/engine/reference/builder/#add)
in the Dockerfile.
The transfer of context from the local machine to the Docker daemon is what the
`docker` client means when you see the "Sending build context" message.
If you wish to keep the intermediate containers after the build is complete,
you must use `--rm=false`. This doesn't affect the build cache.
### Build with URL
```console
$ docker build github.com/creack/docker-firefox
```
This clones the GitHub repository, using the cloned repository as context,
and the Dockerfile at the root of the repository. You can
specify an arbitrary Git repository by using the `git://` or `git@` scheme.
```console
$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz
Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B
Step 1/3 : FROM busybox
---> 8c2e06607696
Step 2/3 : ADD ctx/container.cfg /
---> e7829950cee3
Removing intermediate container b35224abf821
Step 3/3 : CMD /bin/ls
---> Running in fbc63d321d73
---> 3286931702ad
Removing intermediate container fbc63d321d73
Successfully built 377c409b35e4
```
This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which
downloads and extracts the referenced tarball. The `-f ctx/Dockerfile`
parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` used
to build the image. Any `ADD` commands in that `Dockerfile` that refer to local
paths must be relative to the root of the contents inside `ctx.tar.gz`. In the
example above, the tarball contains a directory `ctx/`, so the `ADD
ctx/container.cfg /` operation works as expected.
### Build with `-`
```console
$ docker build - < Dockerfile
```
This example reads a Dockerfile from `STDIN` without context. Due to the lack of a
context, the command doesn't send contents of any local directory to the Docker daemon.
Since there is no context, a Dockerfile `ADD` only works if it refers to a
remote URL.
```console
$ docker build - < context.tar.gz
```
This example builds an image for a compressed context read from `STDIN`.
Supported formats are: `bzip2`, `gzip` and `xz`.
### Use a .dockerignore file
```console
$ docker build .
Uploading context 18.829 MB
Uploading context
Step 1/2 : FROM busybox
---> 769b9341d937
Step 2/2 : CMD echo Hello world
---> Using cache
---> 99cc1ad10469
Successfully built 99cc1ad10469
$ echo ".git" > .dockerignore
$ docker build .
Uploading context 6.76 MB
Uploading context
Step 1/2 : FROM busybox
---> 769b9341d937
Step 2/2 : CMD echo Hello world
---> Using cache
---> 99cc1ad10469
Successfully built 99cc1ad10469
```
This example shows the use of the `.dockerignore` file to exclude the `.git`
directory from the context. You can see its effect in the changed size of the
uploaded context. The builder reference contains detailed information on
[creating a .dockerignore file](https://docs.docker.com/engine/reference/builder/#dockerignore-file).
When using the [BuildKit backend](https://docs.docker.com/build/buildkit/),
`docker build` searches for a `.dockerignore` file relative to the Dockerfile
name. For example, running `docker build -f myapp.Dockerfile .` first looks
for an ignore file named `myapp.Dockerfile.dockerignore`. If it can't find such a file,
if present, it uses the `.dockerignore` file. Using a Dockerfile based
`.dockerignore` is useful if a project contains multiple Dockerfiles that expect
to ignore different sets of files.
### <a name="tag"></a> Tag an image (-t, --tag)
```console
$ docker build -t vieux/apache:2.0 .
```
This examples builds in the same way as the previous example, but it then tags the resulting
image. The repository name will be `vieux/apache` and the tag `2.0`.
[Read more about valid tags](tag.md).
You can apply multiple tags to an image. For example, you can apply the `latest`
tag to a newly built image and add another tag that references a specific
version.
For example, to tag an image both as `whenry/fedora-jboss:latest` and
`whenry/fedora-jboss:v2.1`, use the following:
```console
$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
```
### <a name="file"></a> Specify a Dockerfile (-f, --file)
```console
$ docker build -f Dockerfile.debug .
```
This uses a file called `Dockerfile.debug` for the build instructions
instead of `Dockerfile`.
```console
$ curl example.com/remote/Dockerfile | docker build -f - .
```
The above command uses the current directory as the build context and reads
a Dockerfile from stdin.
```console
$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod .
```
The above commands build the current build context (as specified by the
`.`) twice. Once using a debug version of a `Dockerfile` and once using a
production version.
```console
$ cd /home/me/myapp/some/dir/really/deep
$ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
$ docker build -f ../../../../dockerfiles/debug /home/me/myapp
```
These two `docker build` commands do the exact same thing. They both use the
contents of the `debug` file instead of looking for a `Dockerfile` and use
`/home/me/myapp` as the root of the build context. Note that `debug` is in the
directory structure of the build context, regardless of how you refer to it on
the command line.
> **Note**
>
> `docker build` returns a `no such file or directory` error if the
> file or directory doesn't exist in the uploaded context. This may
> happen if there is no context, or if you specify a file that's
> elsewhere on the Host system. The context is limited to the current
> directory (and its children) for security reasons, and to ensure
> repeatable builds on remote Docker hosts. This is also the reason why
> `ADD ../file` doesn't work.
### <a name="cgroup-parent"></a> Use a custom parent cgroup (--cgroup-parent)
When you run `docker build` with the `--cgroup-parent` option, the daemon runs the containers
used in the build with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups).
### <a name="ulimit"></a> Set ulimits in container (--ulimit)
Using the `--ulimit` option with `docker build` causes the daemon to start each build step's
container using those [`--ulimit` flag values](run.md#ulimit).
### <a name="build-arg"></a> Set build-time variables (--build-arg)
You can use `ENV` instructions in a Dockerfile to define variable values. These
values persist in the built image. Often persistence isn't what you want. Users
want to specify variables differently depending on which host they build an
image on.
A good example is `http_proxy` or source versions for pulling intermediate
files. The `ARG` instruction lets Dockerfile authors define values that users
can set at build-time using the `--build-arg` flag:
```console
$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .
```
This flag allows you to pass the build-time variables that are
accessed like regular environment variables in the `RUN` instruction of the
Dockerfile. These values don't persist in the intermediate or final images
like `ENV` values do. You must add `--build-arg` for each build argument.
Using this flag doesn't alter the output you see when the build process echoes the`ARG` lines from the
Dockerfile.
For detailed information on using `ARG` and `ENV` instructions, see the
[Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
You can also use the `--build-arg` flag without a value, in which case the daemon
propagates the value from the local environment into the Docker container it's building:
```console
$ export HTTP_PROXY=http://10.20.30.2:1234
$ docker build --build-arg HTTP_PROXY .
```
This example is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env)
for more information.
### <a name="security-opt"></a> Optional security options (--security-opt)
This flag is only supported on a daemon running on Windows, and only supports
the `credentialspec` option. The `credentialspec` must be in the format
`file://spec.txt` or `registry://keyname`.
### <a name="isolation"></a> Specify isolation technology for container (--isolation)
This option is useful in situations where you are running Docker containers on
Windows. The `--isolation=<value>` option sets a container's isolation
technology. On Linux, the only supported is the `default` option which uses
Linux namespaces. On Microsoft Windows, you can specify these values:
| Value | Description |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. |
| `process` | Namespace isolation only. |
| `hyperv` | Hyper-V hypervisor partition-based isolation. |
Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
### <a name="add-host"></a> Add entries to container hosts file (--add-host)
You can add other hosts into a build container's `/etc/hosts` file by using one
or more `--add-host` flags. This example adds static addresses for hosts named
`my-hostname` and `my_hostname_v6`:
```console
$ docker build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .
```
If you need your build to connect to services running on the host, you can use
the special `host-gateway` value for `--add-host`. In the following example,
build containers resolve `host.docker.internal` to the host's gateway IP.
```console
$ docker build --add-host host.docker.internal=host-gateway .
```
You can wrap an IPv6 address in square brackets.
`=` and `:` are both valid separators.
Both formats in the following example are valid:
```console
$ docker build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .
```
### <a name="target"></a> Specifying target build stage (--target)
When building a Dockerfile with multiple build stages, you can use the `--target`
option to specify an intermediate build stage by name as a final stage for the
resulting image. The daemon skips commands after the target stage.
```dockerfile
FROM debian AS build-env
# ...
FROM alpine AS production-env
# ...
```
```console
$ docker build -t mybuildimage --target build-env .
```
### <a name="output"></a> Custom build outputs (--output)
> **Note**
>
> This feature requires the BuildKit backend. You can either
> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
> use the [buildx](https://github.com/docker/buildx) plugin which provides more
> output type options.
By default, a local container image is created from the build result. The
`--output` (or `-o`) flag allows you to override this behavior, and specify a
custom exporter. Custom exporters allow you to export the build
artifacts as files on the local filesystem instead of a Docker image, which can
be useful for generating local binaries, code generation etc.
The value for `--output` is a CSV-formatted string defining the exporter type
and options that supports `local` and `tar` exporters.
The `local` exporter writes the resulting build files to a directory on the client side. The
`tar` exporter is similar but writes the files as a single tarball (`.tar`).
If you specify no type, the value defaults to the output directory of the local
exporter. Use a hyphen (`-`) to write the output tarball to standard output
(`STDOUT`).
The following example builds an image using the current directory (`.`) as a build
context, and exports the files to a directory named `out` in the current directory.
If the directory does not exist, Docker creates the directory automatically:
```console
$ docker build -o out .
```
The example above uses the short-hand syntax, omitting the `type` options, and
thus uses the default (`local`) exporter. The example below shows the equivalent
using the long-hand CSV syntax, specifying both `type` and `dest` (destination
path):
```console
$ docker build --output type=local,dest=out .
```
Use the `tar` type to export the files as a `.tar` archive:
```console
$ docker build --output type=tar,dest=out.tar .
```
The example below shows the equivalent when using the short-hand syntax. In this
case, `-` is specified as destination, which automatically selects the `tar` type,
and writes the output tarball to standard output, which is then redirected to
the `out.tar` file:
```console
$ docker build -o - . > out.tar
```
The `--output` option exports all files from the target stage. A common pattern
for exporting only specific files is to do multi-stage builds and to copy the
desired files to a new scratch stage with [`COPY --from`](https://docs.docker.com/engine/reference/builder/#copy).
The example, the `Dockerfile` below uses a separate stage to collect the
build artifacts for exporting:
```dockerfile
FROM golang AS build-stage
RUN go get -u github.com/LK4D4/vndr
FROM scratch AS export-stage
COPY --from=build-stage /go/bin/vndr /
```
When building the Dockerfile with the `-o` option, the command only exports the files from the final
stage to the `out` directory, in this case, the `vndr` binary:
```console
$ docker build -o out .
[+] Building 2.3s (7/7) FINISHED
=> [internal] load build definition from Dockerfile 0.1s
=> => transferring dockerfile: 176B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
=> [internal] load metadata for docker.io/library/golang:latest 1.6s
=> [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s
=> => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s
=> CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s
=> [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s
=> exporting to client 0.4s
=> => copying files 10.30MB 0.3s
$ ls ./out
vndr
```
### <a name="cache-from"></a> Specifying external cache sources (--cache-from)
> **Note**
>
> This feature requires the BuildKit backend. You can either
> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
> use the [buildx](https://github.com/docker/buildx) plugin. The previous
> builder has limited support for reusing cache from pre-pulled images.
In addition to local build cache, the builder can reuse the cache generated from
previous builds with the `--cache-from` flag pointing to an image in the registry.
To use an image as a cache source, cache metadata needs to be written into the
image on creation. You can do this by setting `--build-arg BUILDKIT_INLINE_CACHE=1`
when building the image. After that, you can use the built image as a cache source
for subsequent builds.
Upon importing the cache, the builder only pulls the JSON metadata from the
registry and determine possible cache hits based on that information. If there
is a cache hit, the builder pulls the matched layers into the local environment.
In addition to images, the cache can also be pulled from special cache manifests
generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI
(`buildctl`). These manifests (when built with the `type=registry` and `mode=max`
options) allow pulling layer data for intermediate stages in multi-stage builds.
The following example builds an image with inline-cache metadata and pushes it
to a registry, then uses the image as a cache source on another machine:
```console
$ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 .
$ docker push myname/myapp
```
After pushing the image, the image is used as cache source on another machine.
BuildKit automatically pulls the image from the registry if needed.
On another machine:
```console
$ docker build --cache-from myname/myapp .
```
### <a name="network"></a> Set the networking mode for the RUN instructions during build (--network)
#### Overview
Available options for the networking mode are:
- `default` (default): Run in the default network.
- `none`: Run with no network access.
- `host`: Run in the host’s network environment.
Find more details in the [Dockerfile documentation](https://docs.docker.com/engine/reference/builder/#run---network).
### <a name="squash"></a> Squash an image's layers (--squash) (experimental)
#### Overview
> **Note**
> The `--squash` option is an experimental feature, and should not be considered
> stable.
Once the image is built, this flag squashes the new layers into a new image with
a single new layer. Squashing doesn't destroy any existing image, rather it
creates a new image with the content of the squashed layers. This effectively
makes it look like all `Dockerfile` commands were created with a single layer.
The `--squash` flag preserves the build cache.
Squashing layers can be beneficial if your Dockerfile produces multiple layers
modifying the same files. For example, files created in one step and
removed in another step. For other use-cases, squashing images may actually have
a negative impact on performance. When pulling an image consisting of multiple
layers, the daemon can pull layers in parallel and allows sharing layers between
images (saving space).
For most use cases, multi-stage builds are a better alternative, as they give more
fine-grained control over your build, and can take advantage of future
optimizations in the builder. Refer to the [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
section for more information.
#### Known limitations
The `--squash` option has a number of known limitations:
- When squashing layers, the resulting image can't take advantage of layer
sharing with other images, and may use significantly more space. Sharing the
base image is still supported.
- When using this option you may see significantly more space used due to
storing two copies of the image, one for the build cache with all the cache
layers intact, and one for the squashed version.
- While squashing layers may produce smaller images, it may have a negative
impact on performance, as a single layer takes longer to extract, and
you can't parallelize downloading a single layer.
- When attempting to squash an image that doesn't make changes to the
filesystem (for example, the Dockerfile only contains `ENV` instructions),
the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)).
#### Prerequisites
The example on this page is using experimental mode in Docker 23.03.
You can enable experimental mode by using the `--experimental` flag when starting
the Docker daemon or setting `experimental: true` in the `daemon.json` configuration
file.
By default, experimental mode is disabled. To see the current configuration of
the Docker daemon, use the `docker version` command and check the `Experimental`
line in the `Engine` section:
```console
Client: Docker Engine - Community
Version: 23.0.3
API version: 1.42
Go version: go1.19.7
Git commit: 3e7cbfd
Built: Tue Apr 4 22:05:41 2023
OS/Arch: darwin/amd64
Context: default
Server: Docker Engine - Community
Engine:
Version: 23.0.3
API version: 1.42 (minimum version 1.12)
Go version: go1.19.7
Git commit: 59118bf
Built: Tue Apr 4 22:05:41 2023
OS/Arch: linux/amd64
Experimental: true
[...]
```
#### Build an image with the `--squash` flag
The following is an example of a build with the `--squash` flag. Below is the
`Dockerfile`:
```dockerfile
FROM busybox
RUN echo hello > /hello
RUN echo world >> /hello
RUN touch remove_me /remove_me
ENV HELLO=world
RUN rm /remove_me
```
Next, build an image named `test` using the `--squash` flag.
```console
$ docker build --squash -t test .
```
After the build completes, the history looks like the below. The history could show that a layer's
name is `<missing>`, and there is a new layer with COMMENT `merge`.
```console
$ docker history test
IMAGE CREATED CREATED BY SIZE COMMENT
4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb
<missing> 5 minutes ago /bin/sh -c rm /remove_me 0 B
<missing> 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B
<missing> 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B
<missing> 5 minutes ago /bin/sh -c echo world >> /hello 0 B
<missing> 6 minutes ago /bin/sh -c echo hello > /hello 0 B
<missing> 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B
<missing> 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB
```
Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is
in `/hello`, make sure the `HELLO` environment variable's value is `world`.

72
docs/reference/commandline/image_history.md
View File

@ -1,4 +1,4 @@
# image history # history
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Show the history of an image Show the history of an image
@ -9,16 +9,70 @@ Show the history of an image
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `-H`, `--human` | | | Print sizes and dates in human readable format | | `-H`, `--human` | | | Print sizes and dates in human readable format |
| `--no-trunc` | | | Don't truncate output | | `--no-trunc` | | | Don't truncate output |
| `-q`, `--quiet` | | | Only show image IDs | | `-q`, `--quiet` | | | Only show image IDs |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Examples
See [docker history](history.md) for more information. To see how the `docker:latest` image was built:
```console
$ docker history docker
IMAGE CREATED CREATED BY SIZE COMMENT
3e23a5875458 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B
8578938dd170 8 days ago /bin/sh -c dpkg-reconfigure locales && loc 1.245 MB
be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get install 338.3 MB
4b137612be55 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB
750d58736b4b 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi <ad 0 B
511136ea3c5a 9 months ago 0 B Imported from -
```
To see how the `docker:apache` image was added to a container's base image:
```console
$ docker history docker:scm
IMAGE CREATED CREATED BY SIZE COMMENT
2ac9d1098bf1 3 months ago /bin/bash 241.4 MB Added Apache to Fedora base image
88b42ffd1f7c 5 months ago /bin/sh -c #(nop) ADD file:1fd8d7f9f6557cafc7 373.7 MB
c69cab00d6ef 5 months ago /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar 0 B
511136ea3c5a 19 months ago 0 B Imported from -
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) will pretty-prints history output
using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|-----------------|-----------------------------------------------------------------------------------------------------------|
| `.ID` | Image ID |
| `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created |
| `.CreatedAt` | Timestamp of when image was created |
| `.CreatedBy` | Command that was used to create the image |
| `.Size` | Image disk size |
| `.Comment` | Comment for image |
When using the `--format` option, the `history` command either
outputs the data exactly as the template declares or, when using the
`table` directive, includes column headers as well.
The following example uses a template without headers and outputs the
`ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox`
image:
```console
$ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox
f6e427c148a7: 4 weeks ago
<missing>: 4 weeks ago
```

72
docs/reference/commandline/image_import.md
View File

@ -1,4 +1,4 @@
# image import # import
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Import the contents from a tarball to create a filesystem image Import the contents from a tarball to create a filesystem image
@ -20,4 +20,72 @@ Import the contents from a tarball to create a filesystem image
## Description ## Description
See [docker import](import.md) for more information. You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The
`URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz)
containing a filesystem or to an individual file on the Docker host. If you
specify an archive, Docker untars it in the container relative to the `/`
(root). If you specify an individual file, you must specify the full path within
the host. To import from a remote location, specify a `URI` that begins with the
`http://` or `https://` protocol.
The `--change` option applies `Dockerfile` instructions to the image that is
created. Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
## Examples
### Import from a remote location
This creates a new untagged image.
```console
$ docker import https://example.com/exampleimage.tgz
```
### Import from a local file
Import to docker via pipe and `STDIN`.
```console
$ cat exampleimage.tgz | docker import - exampleimagelocal:new
```
Import with a commit message.
```console
$ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new
```
Import to docker from a local archive.
```console
$ docker import /path/to/exampleimage.tgz
```
### Import from a local directory
```console
$ sudo tar -c . | docker import - exampleimagedir
```
### Import from a local directory with new configurations
```console
$ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir
```
Note the `sudo` in this example – you must preserve
the ownership of the files (especially root ownership) during the
archiving with tar. If you are not root (or the sudo command) when you
tar, then the ownerships might not get preserved.
## When the daemon supports multiple operating systems
If the daemon supports multiple operating systems, and the image being imported
does not match the default operating system, it may be necessary to add
`--platform`. This would be necessary when importing a Linux image into a Windows
daemon.
```console
$ docker import --platform=linux .\linuximage.tar
```

50
docs/reference/commandline/image_load.md
View File

@ -1,4 +1,4 @@
# image load # load
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Load an image from a tar archive or STDIN Load an image from a tar archive or STDIN
@ -9,14 +9,52 @@ Load an image from a tar archive or STDIN
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------|:---------|:--------|:---------------------------------------------| |:------------------------------------|:---------|:--------|:---------------------------------------------|
| `-i`, `--input` | `string` | | Read from tar archive file, instead of STDIN | | [`-i`](#input), [`--input`](#input) | `string` | | Read from tar archive file, instead of STDIN |
| `-q`, `--quiet` | | | Suppress the load output | | `-q`, `--quiet` | | | Suppress the load output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker load](load.md) for more information. Load an image or repository from a tar archive (even if compressed with gzip,
bzip2, xz or zstd) from a file or STDIN. It restores both images and tags.
## Examples
```console
$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
```
### Load images from STDIN
```console
$ docker load < busybox.tar.gz
Loaded image: busybox:latest
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox latest 769b9341d937 7 weeks ago 2.489 MB
```
### <a name="input"></a> Load images from a file (--input)
```console
$ docker load --input fedora.tar
Loaded image: fedora:rawhide
Loaded image: fedora:20
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox latest 769b9341d937 7 weeks ago 2.489 MB
fedora rawhide 0d20aec6529d 7 weeks ago 387 MB
fedora 20 58394af37342 7 weeks ago 385.5 MB
fedora heisenbug 58394af37342 7 weeks ago 385.5 MB
fedora latest 58394af37342 7 weeks ago 385.5 MB
```

340
docs/reference/commandline/image_ls.md
View File

@ -1,4 +1,4 @@
# image ls # images
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
List images List images
@ -9,18 +9,338 @@ List images
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-a`, `--all` | | | Show all images (default hides intermediate images) | | `-a`, `--all` | | | Show all images (default hides intermediate images) |
| `--digests` | | | Show digests | | [`--digests`](#digests) | | | Show digests |
| `-f`, `--filter` | `filter` | | Filter output based on conditions provided | | [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
| `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `--no-trunc` | | | Don't truncate output | | [`--no-trunc`](#no-trunc) | | | Don't truncate output |
| `-q`, `--quiet` | | | Only show image IDs | | `-q`, `--quiet` | | | Only show image IDs |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker images](images.md) for more information. The default `docker images` will show all top level
images, their repository and tags, and their size.
Docker images have intermediate layers that increase reusability,
decrease disk usage, and speed up `docker build` by
allowing each step to be cached. These intermediate layers are not shown
by default.
The `SIZE` is the cumulative space taken up by the image and all
its parent images. This is also the disk space used by the contents of the
Tar file created when you `docker save` an image.
An image will be listed more than once if it has multiple repository names
or tags. This single image (identifiable by its matching `IMAGE ID`)
uses up the `SIZE` listed only once.
## Examples
### List the most recently created images
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> 77af4d6b9913 19 hours ago 1.089 GB
committ latest b6fa739cedf5 19 hours ago 1.089 GB
<none> <none> 78a85c484f71 19 hours ago 1.089 GB
docker latest 30557a29d5ab 20 hours ago 1.089 GB
<none> <none> 5ed6274db6ce 24 hours ago 1.089 GB
postgres 9 746b819f315e 4 days ago 213.4 MB
postgres 9.3 746b819f315e 4 days ago 213.4 MB
postgres 9.3.5 746b819f315e 4 days ago 213.4 MB
postgres latest 746b819f315e 4 days ago 213.4 MB
```
### List images by name and tag
The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument
that restricts the list to images that match the argument. If you specify
`REPOSITORY`but no `TAG`, the `docker images` command lists all images in the
given repository.
For example, to list all images in the `java` repository, run the following command:
```console
$ docker images java
REPOSITORY TAG IMAGE ID CREATED SIZE
java 8 308e519aac60 6 days ago 824.5 MB
java 7 493d82594c15 3 months ago 656.3 MB
java latest 2711b1d6f3aa 5 months ago 603.9 MB
```
The `[REPOSITORY[:TAG]]` value must be an exact match. This means that, for example,
`docker images jav` does not match the image `java`.
If both `REPOSITORY` and `TAG` are provided, only images matching that
repository and tag are listed. To find all local images in the `java`
repository with tag `8` you can use:
```console
$ docker images java:8
REPOSITORY TAG IMAGE ID CREATED SIZE
java 8 308e519aac60 6 days ago 824.5 MB
```
If nothing matches `REPOSITORY[:TAG]`, the list is empty.
```console
$ docker images java:0
REPOSITORY TAG IMAGE ID CREATED SIZE
```
### <a name="no-trunc"></a> List the full length image IDs (--no-trunc)
```console
$ docker images --no-trunc
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB
committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB
<none> <none> sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB
docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB
<none> <none> sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB
<none> <none> sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB
<none> <none> sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB
tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB
<none> <none> sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB
```
### <a name="digests"></a> List image digests (--digests)
Images that use the v2 or later format have a content-addressable identifier
called a `digest`. As long as the input used to generate the image is
unchanged, the digest value is predictable. To list image digest values, use
the `--digests` flag:
```console
$ docker images --digests
REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB
```
When pushing or pulling to a 2.0 registry, the `push` or `pull` command
output includes the image digest. You can `pull` using a digest value. You can
also reference by digest in `create`, `run`, and `rmi` commands, as well as the
`FROM` image reference in a Dockerfile.
### <a name="filter"></a> Filtering (--filter)
The filtering flag (`-f` or `--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"`).
The currently supported filters are:
* dangling (boolean - true or false)
* label (`label=<key>` or `label=<key>=<value>`)
* before (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created before given id or references
* since (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created since given id or references
* reference (pattern of an image reference) - filter images whose reference matches the specified pattern
#### Show untagged images (dangling)
```console
$ docker images --filter "dangling=true"
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> 8abc22fbb042 4 weeks ago 0 B
<none> <none> 48e5f45168b9 4 weeks ago 2.489 MB
<none> <none> bf747efa0e2f 4 weeks ago 0 B
<none> <none> 980fe10e5736 12 weeks ago 101.4 MB
<none> <none> dea752e4e117 12 weeks ago 101.4 MB
<none> <none> 511136ea3c5a 8 months ago 0 B
```
This will display untagged images that are the leaves of the images tree (not
intermediary layers). These images occur when a new build of an image takes the
`repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged.
A warning will be issued if trying to remove an image when a container is presently
using it. By having this flag it allows for batch cleanup.
You can use this in conjunction with `docker rmi`:
```console
$ docker rmi $(docker images -f "dangling=true" -q)
8abc22fbb042
48e5f45168b9
bf747efa0e2f
980fe10e5736
dea752e4e117
511136ea3c5a
```
Docker warns you if any containers exist that are using these untagged images.
#### Show images with a given label
The `label` filter matches images based on the presence of a `label` alone or a `label` and a
value.
The following filter matches images with the `com.example.version` label regardless of its value.
```console
$ docker images --filter "label=com.example.version"
REPOSITORY TAG IMAGE ID CREATED SIZE
match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB
match-me-2 latest dea752e4e117 About a minute ago 188.3 MB
```
The following filter matches images with the `com.example.version` label with the `1.0` value.
```console
$ docker images --filter "label=com.example.version=1.0"
REPOSITORY TAG IMAGE ID CREATED SIZE
match-me latest 511136ea3c5a About a minute ago 188.3 MB
```
In this example, with the `0.1` value, it returns an empty set because no matches were found.
```console
$ docker images --filter "label=com.example.version=0.1"
REPOSITORY TAG IMAGE ID CREATED SIZE
```
#### Filter images by time
The `before` filter shows only images created before the image with
a given ID or reference. For example, having these images:
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
image2 latest dea752e4e117 9 minutes ago 188.3 MB
image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
```
Filtering with `before` would give:
```console
$ docker images --filter "before=image1"
REPOSITORY TAG IMAGE ID CREATED SIZE
image2 latest dea752e4e117 9 minutes ago 188.3 MB
image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
```
Filtering with `since` would give:
```console
$ docker images --filter "since=image3"
REPOSITORY TAG IMAGE ID CREATED SIZE
image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
image2 latest dea752e4e117 9 minutes ago 188.3 MB
```
#### Filter images by reference
The `reference` filter shows only images whose reference matches
the specified pattern.
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox latest e02e811dd08f 5 weeks ago 1.09 MB
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox musl 733eb3059dce 5 weeks ago 1.21 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
Filtering with `reference` would give:
```console
$ docker images --filter=reference='busy*:*libc'
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
Filtering with multiple `reference` would give, either match A or B:
```console
$ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc'
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) will pretty print container output
using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|-----------------|------------------------------------------|
| `.ID` | Image ID |
| `.Repository` | Image repository |
| `.Tag` | Image tag |
| `.Digest` | Image digest |
| `.CreatedSince` | Elapsed time since the image was created |
| `.CreatedAt` | Time when the image was created |
| `.Size` | Image disk size |
When using the `--format` option, the `image` command will either
output the data exactly as the template declares or, when using the
`table` directive, will include column headers as well.
The following example uses a template without headers and outputs the
`ID` and `Repository` entries separated by a colon (`:`) for all images:
```console
$ docker images --format "{{.ID}}: {{.Repository}}"
77af4d6b9913: <none>
b6fa739cedf5: committ
78a85c484f71: <none>
30557a29d5ab: docker
5ed6274db6ce: <none>
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
```
To list all images with their repository and tag in a table format you
can use:
```console
$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
77af4d6b9913 <none> <none>
b6fa739cedf5 committ latest
78a85c484f71 <none> <none>
30557a29d5ab docker latest
5ed6274db6ce <none> <none>
746b819f315e postgres 9
746b819f315e postgres 9.3
746b819f315e postgres 9.3.5
746b819f315e postgres latest
```
To list all images in JSON format, use the `json` directive:
```console
$ docker images --format json
{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"}
{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"}
```

236
docs/reference/commandline/image_pull.md
View File

@ -1,4 +1,4 @@
# image pull # pull
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Download an image from a registry Download an image from a registry
@ -9,16 +9,236 @@ Download an image from a registry
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:--------------------------|:---------|:--------|:-------------------------------------------------| |:---------------------------------------------|:---------|:--------|:-------------------------------------------------|
| `-a`, `--all-tags` | | | Download all tagged images in the repository | | [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Download all tagged images in the repository |
| `--disable-content-trust` | | | Skip image verification | | `--disable-content-trust` | | | Skip image verification |
| `--platform` | `string` | | Set platform if server is multi-platform capable | | `--platform` | `string` | | Set platform if server is multi-platform capable |
| `-q`, `--quiet` | | | Suppress verbose output | | `-q`, `--quiet` | | | Suppress verbose output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker pull](pull.md) for more information. Most of your images will be created on top of a base image from the
[Docker Hub](https://hub.docker.com) registry.
[Docker Hub](https://hub.docker.com) contains many pre-built images that you
can `pull` and try without needing to define and configure your own.
To download a particular image, or set of images (i.e., a repository),
use `docker pull`.
### Proxy configuration
If you are behind an HTTP proxy server, for example in corporate settings,
before open a connect to registry, you may need to configure the Docker
daemon's proxy settings, refer to the [dockerd command-line reference](dockerd.md#proxy-configuration)
for details.
### Concurrent downloads
By default the Docker daemon will pull three layers of an image at a time.
If you are on a low bandwidth connection this may cause timeout issues and you may want to lower
this via the `--max-concurrent-downloads` daemon option. See the
[daemon documentation](dockerd.md) for more details.
## Examples
### Pull an image from Docker Hub
To download a particular image, or set of images (i.e., a repository), use
`docker image pull` (or the `docker pull` shorthand). If no tag is provided,
Docker Engine uses the `:latest` tag as a default. This example pulls the
`debian:latest` image:
```console
$ docker image pull debian
Using default tag: latest
latest: Pulling from library/debian
e756f3fdd6a3: Pull complete
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:latest
docker.io/library/debian:latest
```
Docker images can consist of multiple layers. In the example above, the image
consists of a single layer; `e756f3fdd6a3`.
Layers can be reused by images. For example, the `debian:bookworm` image shares
its layer with the `debian:latest`. Pulling the `debian:bookworm` image therefore
only pulls its metadata, but not its layers, because the layer is already present
locally:
```console
$ docker image pull debian:bookworm
bookworm: Pulling from library/debian
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm
```
To see which images are present locally, use the [`docker images`](images.md)
command:
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
debian bookworm 4eacea30377a 8 days ago 124MB
debian latest 4eacea30377a 8 days ago 124MB
```
Docker uses a content-addressable image store, and the image ID is a SHA256
digest covering the image's configuration and layers. In the example above,
`debian:bookworm` and `debian:latest` have the same image ID because they are
the same image tagged with different names. Because they are the same image,
their layers are stored only once and do not consume extra disk space.
For more information about images, layers, and the content-addressable store,
refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/).
### Pull an image by digest (immutable identifier)
So far, you've pulled images by their name (and "tag"). Using names and tags is
a convenient way to work with images. When using tags, you can `docker pull` an
image again to make sure you have the most up-to-date version of that image.
For example, `docker pull ubuntu:22.04` pulls the latest version of the Ubuntu
22.04 image.
In some cases you don't want images to be updated to newer versions, but prefer
to use a fixed version of an image. Docker enables you to pull an image by its
digest. When pulling an image by digest, you specify exactly which version
of an image to pull. Doing so, allows you to "pin" an image to that version,
and guarantee that the image you're using is always the same.
To know the digest of an image, pull the image first. Let's pull the latest
`ubuntu:22.04` image from Docker Hub:
```console
$ docker pull ubuntu:22.04
22.04: Pulling from library/ubuntu
125a6e411906: Pull complete
Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
Status: Downloaded newer image for ubuntu:22.04
docker.io/library/ubuntu:22.04
```
Docker prints the digest of the image after the pull has finished. In the example
above, the digest of the image is:
```console
sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
```
Docker also prints the digest of an image when pushing to a registry. This
may be useful if you want to pin to a version of the image you just pushed.
A digest takes the place of the tag when pulling an image, for example, to
pull the above image by digest, run the following command:
```console
$ docker pull ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d: Pulling from library/ubuntu
Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
Status: Image is up to date for ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
```
Digest can also be used in the `FROM` of a Dockerfile, for example:
```dockerfile
FROM ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
LABEL org.opencontainers.image.authors="some maintainer <maintainer@example.com>"
```
> **Note**
>
> Using this feature "pins" an image to a specific version in time.
> Docker does therefore not pull updated versions of an image, which may include
> security updates. If you want to pull an updated image, you need to change the
> digest accordingly.
### Pull from a different registry
By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to
manually specify the path of a registry to pull from. For example, if you have
set up a local registry, you can specify its path to pull from it. A registry
path is similar to a URL, but does not contain a protocol specifier (`https://`).
The following command pulls the `testing/test-image` image from a local registry
listening on port 5000 (`myregistry.local:5000`):
```console
$ docker image pull myregistry.local:5000/testing/test-image
```
Registry credentials are managed by [docker login](login.md).
Docker uses the `https://` protocol to communicate with a registry, unless the
registry is allowed to be accessed over an insecure connection. Refer to the
[insecure registries](dockerd.md#insecure-registries) section for more information.
### <a name="all-tags"></a> Pull a repository with multiple images (-a, --all-tags)
By default, `docker pull` pulls a single image from the registry. A repository
can contain multiple images. To pull all images from a repository, provide the
`-a` (or `--all-tags`) option when using `docker pull`.
This command pulls all images from the `ubuntu` repository:
```console
$ docker image pull --all-tags ubuntu
Pulling repository ubuntu
ad57ef8d78d7: Download complete
105182bb5e8b: Download complete
511136ea3c5a: Download complete
73bd853d2ea5: Download complete
....
Status: Downloaded newer image for ubuntu
```
After the pull has completed use the `docker image ls` command (or the `docker images`
shorthand) to see the images that were pulled. The example below shows all the
`ubuntu` images that are present locally:
```console
$ docker image ls --filter reference=ubuntu
REPOSITORY TAG IMAGE ID CREATED SIZE
ubuntu 18.04 c6ad7e71ba7d 5 weeks ago 63.2MB
ubuntu bionic c6ad7e71ba7d 5 weeks ago 63.2MB
ubuntu 22.04 5ccefbfc0416 2 months ago 78MB
ubuntu focal ff0fea8310f3 2 months ago 72.8MB
ubuntu latest ff0fea8310f3 2 months ago 72.8MB
ubuntu jammy 41ba606c8ab9 3 months ago 79MB
ubuntu 20.04 ba6acccedd29 7 months ago 72.8MB
```
### Cancel a pull
Killing the `docker pull` process, for example by pressing `CTRL-c` while it is
running in a terminal, will terminate the pull operation.
```console
$ docker pull ubuntu
Using default tag: latest
latest: Pulling from library/ubuntu
a3ed95caeb02: Pulling fs layer
236608c7b546: Pulling fs layer
^C
```
The Engine terminates a pull operation when the connection between the daemon
and the client (initiating the pull) is cut or lost for any reason or the
command is manually terminated.

113
docs/reference/commandline/image_push.md
View File

@ -1,4 +1,4 @@
# image push # push
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Upload an image to a registry Upload an image to a registry
@ -9,15 +9,114 @@ Upload an image to a registry
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:--------------------------|:-----|:--------|:--------------------------------------------| |:---------------------------------------------|:-----|:--------|:--------------------------------------------|
| `-a`, `--all-tags` | | | Push all tags of an image to the repository | | [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Push all tags of an image to the repository |
| `--disable-content-trust` | | | Skip image signing | | `--disable-content-trust` | | | Skip image signing |
| `-q`, `--quiet` | | | Suppress verbose output | | `-q`, `--quiet` | | | Suppress verbose output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
See [docker push](push.md) for more information. Use `docker image push` to share your images to the [Docker Hub](https://hub.docker.com)
registry or to a self-hosted one.
Refer to the [`docker image tag`](tag.md) reference for more information about valid
image and tag names.
Killing the `docker image push` process, for example by pressing `CTRL-c` while it is
running in a terminal, terminates the push operation.
Progress bars are shown during docker push, which show the uncompressed size.
The actual amount of data that's pushed will be compressed before sending, so
the uploaded size will not be reflected by the progress bar.
Registry credentials are managed by [docker login](login.md).
### Concurrent uploads
By default the Docker daemon will push five layers of an image at a time.
If you are on a low bandwidth connection this may cause timeout issues and you may want to lower
this via the `--max-concurrent-uploads` daemon option. See the
[daemon documentation](dockerd.md) for more details.
## Examples
### Push a new image to a registry
First save the new image by finding the container ID (using [`docker container ls`](ps.md))
and then committing it to a new image name. Note that only `a-z0-9-_.` are
allowed when naming images:
```console
$ docker container commit c16378f943fe rhel-httpd:latest
```
Now, push the image to the registry using the image ID. In this example the
registry is on host named `registry-host` and listening on port `5000`. To do
this, tag the image with the host name or IP address, and the port of the
registry:
```console
$ docker image tag rhel-httpd:latest registry-host:5000/myadmin/rhel-httpd:latest
$ docker image push registry-host:5000/myadmin/rhel-httpd:latest
```
Check that this worked by running:
```console
$ docker image ls
```
You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd`
listed.
### <a name="all-tags"></a> Push all tags of an image (-a, --all-tags)
Use the `-a` (or `--all-tags`) option to push all tags of a local image.
The following example creates multiple tags for an image, and pushes all those
tags to Docker Hub.
```console
$ docker image tag myimage registry-host:5000/myname/myimage:latest
$ docker image tag myimage registry-host:5000/myname/myimage:v1.0.1
$ docker image tag myimage registry-host:5000/myname/myimage:v1.0
$ docker image tag myimage registry-host:5000/myname/myimage:v1
```
The image is now tagged under multiple names:
```console
$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage v1 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage v1.0 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage v1.0.1 6d5fcfe5ff17 2 hours ago 1.22MB
```
When pushing with the `--all-tags` option, all tags of the `registry-host:5000/myname/myimage`
image are pushed:
```console
$ docker image push --all-tags registry-host:5000/myname/myimage
The push refers to repository [registry-host:5000/myname/myimage]
195be5f8be1d: Pushed
latest: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1.0: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1.0.1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
```

89
docs/reference/commandline/image_rm.md
View File

@ -1,4 +1,4 @@
# image rm # rmi
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Remove one or more images Remove one or more images
@ -19,4 +19,89 @@ Remove one or more images
## Description ## Description
See [docker rmi](rmi.md) for more information. Removes (and un-tags) one or more images from the host node. If an image has
multiple tags, using this command with the tag as a parameter only removes the
tag. If the tag is the only one for the image, both the image and the tag are
removed.
This does not remove images from a registry. You cannot remove an image of a
running container unless you use the `-f` option. To see all images on a host
use the [`docker image ls`](images.md) command.
## Examples
You can remove an image using its short or long ID, its tag, or its digest. If
an image has one or more tags referencing it, you must remove all of them before
the image is removed. Digest references are removed automatically when an image
is removed by tag.
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
$ docker rmi fd484f19954f
Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force
2013/12/11 05:47:16 Error: failed to remove one or more images
$ docker rmi test1:latest
Untagged: test1:latest
$ docker rmi test2:latest
Untagged: test2:latest
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
$ docker rmi test:latest
Untagged: test:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```
If you use the `-f` flag and specify the image's short or long ID, then this
command untags and removes all images that match the specified ID.
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
$ docker rmi -f fd484f19954f
Untagged: test1:latest
Untagged: test:latest
Untagged: test2:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```
An image pulled by digest has no tag associated with it:
```console
$ docker images --digests
REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB
```
To remove an image using its digest:
```console
$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
```

44
docs/reference/commandline/image_save.md
View File

@ -1,4 +1,4 @@
# image save # save
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Save one or more images to a tar archive (streamed to STDOUT by default) Save one or more images to a tar archive (streamed to STDOUT by default)
@ -18,4 +18,44 @@ Save one or more images to a tar archive (streamed to STDOUT by default)
## Description ## Description
See [docker save](save.md) for more information. Produces a tarred repository to the standard output stream.
Contains all parent layers, and all tags + versions, or specified `repo:tag`, for
each argument provided.
## Examples
### Create a backup that can then be used with `docker load`.
```console
$ docker save busybox > busybox.tar
$ ls -sh busybox.tar
2.7M busybox.tar
$ docker save --output busybox.tar busybox
$ ls -sh busybox.tar
2.7M busybox.tar
$ docker save -o fedora-all.tar fedora
$ docker save -o fedora-latest.tar fedora:latest
```
### Save an image to a tar.gz file using gzip
You can use gzip to save the image file and make the backup smaller.
```console
$ docker save myimage:latest | gzip > myimage_latest.tar.gz
```
### Cherry-pick particular tags
You can even cherry-pick particular tags of an image repository.
```console
$ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy
```

76
docs/reference/commandline/image_tag.md
View File

@ -1,4 +1,4 @@
# image tag # tag
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
@ -12,4 +12,76 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
## Description ## Description
See [docker tag](tag.md) for more information. A full image name has the following format and components:
`[HOST[:PORT_NUMBER]/]PATH`
- `HOST`: The optional registry hostname specifies where the image is located.
The hostname must comply with standard DNS rules, but may not contain
underscores. If you don't specify a hostname, the command uses Docker's public
registry at `registry-1.docker.io` by default. Note that `docker.io` is the
canonical reference for Docker's public registry.
- `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a
registry port number in the format `:8080`.
- `PATH`: The path consists of slash-separated components. Each
component may contain lowercase letters, digits and separators. A separator is
defined as a period, one or two underscores, or one or more hyphens. A component
may not start or end with a separator. While the
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)
supports more than two slash-separated components, most registries only support
two slash-separated components. For Docker's public registry, the path format is
as follows:
- `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a
user's or an organization's namespace. The second, mandatory component is the
repository name. When the namespace is not present, Docker uses `library`
as the default namespace.
After the image name, the optional `TAG` is a custom, human-readable manifest
identifier that's typically a specific version or variant of an image. The tag
must be valid ASCII and can contain lowercase and uppercase letters, digits,
underscores, periods, and hyphens. It can't start with a period or hyphen and
must be no longer than 128 characters. If you don't specify a tag, the command uses `latest` by default.
You can group your images together using names and tags, and then
[push](https://docs.docker.com/engine/reference/commandline/push) them to a
registry.
## Examples
### Tag an image referenced by ID
To tag a local image with ID `0e5574283393` as `fedora/httpd` with the tag
`version1.0`:
```console
$ docker tag 0e5574283393 fedora/httpd:version1.0
```
### Tag an image referenced by Name
To tag a local image `httpd` as `fedora/httpd` with the tag `version1.0`:
```console
$ docker tag httpd fedora/httpd:version1.0
```
Note that since the tag name isn't specified, the alias is created for an
existing local version `httpd:latest`.
### Tag an image referenced by Name and Tag
To tag a local image with the name `httpd` and the tag `test` as `fedora/httpd`
with the tag `version1.0.test`:
```console
$ docker tag httpd:test fedora/httpd:version1.0.test
```
### Tag an image for a private registry
To push an image to a private registry and not the public Docker registry you
must include the registry hostname and port (if needed).
```console
$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0
```

341
docs/reference/commandline/images.md
View File

@ -1,4 +1,4 @@
# images # docker images
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
List images List images
@ -9,338 +9,15 @@ List images
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-a`, `--all` | | | Show all images (default hides intermediate images) | | `-a`, `--all` | | | Show all images (default hides intermediate images) |
| [`--digests`](#digests) | | | Show digests | | `--digests` | | | Show digests |
| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | | `-f`, `--filter` | `filter` | | Filter output based on conditions provided |
| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| [`--no-trunc`](#no-trunc) | | | Don't truncate output | | `--no-trunc` | | | Don't truncate output |
| `-q`, `--quiet` | | | Only show image IDs | | `-q`, `--quiet` | | | Only show image IDs |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The default `docker images` will show all top level
images, their repository and tags, and their size.
Docker images have intermediate layers that increase reusability,
decrease disk usage, and speed up `docker build` by
allowing each step to be cached. These intermediate layers are not shown
by default.
The `SIZE` is the cumulative space taken up by the image and all
its parent images. This is also the disk space used by the contents of the
Tar file created when you `docker save` an image.
An image will be listed more than once if it has multiple repository names
or tags. This single image (identifiable by its matching `IMAGE ID`)
uses up the `SIZE` listed only once.
## Examples
### List the most recently created images
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> 77af4d6b9913 19 hours ago 1.089 GB
committ latest b6fa739cedf5 19 hours ago 1.089 GB
<none> <none> 78a85c484f71 19 hours ago 1.089 GB
docker latest 30557a29d5ab 20 hours ago 1.089 GB
<none> <none> 5ed6274db6ce 24 hours ago 1.089 GB
postgres 9 746b819f315e 4 days ago 213.4 MB
postgres 9.3 746b819f315e 4 days ago 213.4 MB
postgres 9.3.5 746b819f315e 4 days ago 213.4 MB
postgres latest 746b819f315e 4 days ago 213.4 MB
```
### List images by name and tag
The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument
that restricts the list to images that match the argument. If you specify
`REPOSITORY`but no `TAG`, the `docker images` command lists all images in the
given repository.
For example, to list all images in the `java` repository, run the following command:
```console
$ docker images java
REPOSITORY TAG IMAGE ID CREATED SIZE
java 8 308e519aac60 6 days ago 824.5 MB
java 7 493d82594c15 3 months ago 656.3 MB
java latest 2711b1d6f3aa 5 months ago 603.9 MB
```
The `[REPOSITORY[:TAG]]` value must be an exact match. This means that, for example,
`docker images jav` does not match the image `java`.
If both `REPOSITORY` and `TAG` are provided, only images matching that
repository and tag are listed. To find all local images in the `java`
repository with tag `8` you can use:
```console
$ docker images java:8
REPOSITORY TAG IMAGE ID CREATED SIZE
java 8 308e519aac60 6 days ago 824.5 MB
```
If nothing matches `REPOSITORY[:TAG]`, the list is empty.
```console
$ docker images java:0
REPOSITORY TAG IMAGE ID CREATED SIZE
```
### <a name="no-trunc"></a> List the full length image IDs (--no-trunc)
```console
$ docker images --no-trunc
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB
committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB
<none> <none> sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB
docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB
<none> <none> sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB
<none> <none> sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB
<none> <none> sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB
tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB
<none> <none> sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB
```
### <a name="digests"></a> List image digests (--digests)
Images that use the v2 or later format have a content-addressable identifier
called a `digest`. As long as the input used to generate the image is
unchanged, the digest value is predictable. To list image digest values, use
the `--digests` flag:
```console
$ docker images --digests
REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB
```
When pushing or pulling to a 2.0 registry, the `push` or `pull` command
output includes the image digest. You can `pull` using a digest value. You can
also reference by digest in `create`, `run`, and `rmi` commands, as well as the
`FROM` image reference in a Dockerfile.
### <a name="filter"></a> Filtering (--filter)
The filtering flag (`-f` or `--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"`).
The currently supported filters are:
* dangling (boolean - true or false)
* label (`label=<key>` or `label=<key>=<value>`)
* before (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created before given id or references
* since (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created since given id or references
* reference (pattern of an image reference) - filter images whose reference matches the specified pattern
#### Show untagged images (dangling)
```console
$ docker images --filter "dangling=true"
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> 8abc22fbb042 4 weeks ago 0 B
<none> <none> 48e5f45168b9 4 weeks ago 2.489 MB
<none> <none> bf747efa0e2f 4 weeks ago 0 B
<none> <none> 980fe10e5736 12 weeks ago 101.4 MB
<none> <none> dea752e4e117 12 weeks ago 101.4 MB
<none> <none> 511136ea3c5a 8 months ago 0 B
```
This will display untagged images that are the leaves of the images tree (not
intermediary layers). These images occur when a new build of an image takes the
`repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged.
A warning will be issued if trying to remove an image when a container is presently
using it. By having this flag it allows for batch cleanup.
You can use this in conjunction with `docker rmi`:
```console
$ docker rmi $(docker images -f "dangling=true" -q)
8abc22fbb042
48e5f45168b9
bf747efa0e2f
980fe10e5736
dea752e4e117
511136ea3c5a
```
Docker warns you if any containers exist that are using these untagged images.
#### Show images with a given label
The `label` filter matches images based on the presence of a `label` alone or a `label` and a
value.
The following filter matches images with the `com.example.version` label regardless of its value.
```console
$ docker images --filter "label=com.example.version"
REPOSITORY TAG IMAGE ID CREATED SIZE
match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB
match-me-2 latest dea752e4e117 About a minute ago 188.3 MB
```
The following filter matches images with the `com.example.version` label with the `1.0` value.
```console
$ docker images --filter "label=com.example.version=1.0"
REPOSITORY TAG IMAGE ID CREATED SIZE
match-me latest 511136ea3c5a About a minute ago 188.3 MB
```
In this example, with the `0.1` value, it returns an empty set because no matches were found.
```console
$ docker images --filter "label=com.example.version=0.1"
REPOSITORY TAG IMAGE ID CREATED SIZE
```
#### Filter images by time
The `before` filter shows only images created before the image with
a given ID or reference. For example, having these images:
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
image2 latest dea752e4e117 9 minutes ago 188.3 MB
image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
```
Filtering with `before` would give:
```console
$ docker images --filter "before=image1"
REPOSITORY TAG IMAGE ID CREATED SIZE
image2 latest dea752e4e117 9 minutes ago 188.3 MB
image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
```
Filtering with `since` would give:
```console
$ docker images --filter "since=image3"
REPOSITORY TAG IMAGE ID CREATED SIZE
image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
image2 latest dea752e4e117 9 minutes ago 188.3 MB
```
#### Filter images by reference
The `reference` filter shows only images whose reference matches
the specified pattern.
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox latest e02e811dd08f 5 weeks ago 1.09 MB
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox musl 733eb3059dce 5 weeks ago 1.21 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
Filtering with `reference` would give:
```console
$ docker images --filter=reference='busy*:*libc'
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
Filtering with multiple `reference` would give, either match A or B:
```console
$ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc'
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) will pretty print container output
using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|-----------------|------------------------------------------|
| `.ID` | Image ID |
| `.Repository` | Image repository |
| `.Tag` | Image tag |
| `.Digest` | Image digest |
| `.CreatedSince` | Elapsed time since the image was created |
| `.CreatedAt` | Time when the image was created |
| `.Size` | Image disk size |
When using the `--format` option, the `image` command will either
output the data exactly as the template declares or, when using the
`table` directive, will include column headers as well.
The following example uses a template without headers and outputs the
`ID` and `Repository` entries separated by a colon (`:`) for all images:
```console
$ docker images --format "{{.ID}}: {{.Repository}}"
77af4d6b9913: <none>
b6fa739cedf5: committ
78a85c484f71: <none>
30557a29d5ab: docker
5ed6274db6ce: <none>
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
```
To list all images with their repository and tag in a table format you
can use:
```console
$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
77af4d6b9913 <none> <none>
b6fa739cedf5 committ latest
78a85c484f71 <none> <none>
30557a29d5ab docker latest
5ed6274db6ce <none> <none>
746b819f315e postgres 9
746b819f315e postgres 9.3
746b819f315e postgres 9.3.5
746b819f315e postgres latest
```
To list all images in JSON format, use the `json` directive:
```console
$ docker images --format json
{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"}
{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"}
```

73
docs/reference/commandline/import.md
View File

@ -1,4 +1,4 @@
# import # docker import
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Import the contents from a tarball to create a filesystem image Import the contents from a tarball to create a filesystem image
@ -18,74 +18,3 @@ Import the contents from a tarball to create a filesystem image
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The
`URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz)
containing a filesystem or to an individual file on the Docker host. If you
specify an archive, Docker untars it in the container relative to the `/`
(root). If you specify an individual file, you must specify the full path within
the host. To import from a remote location, specify a `URI` that begins with the
`http://` or `https://` protocol.
The `--change` option applies `Dockerfile` instructions to the image that is
created. Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
## Examples
### Import from a remote location
This creates a new untagged image.
```console
$ docker import https://example.com/exampleimage.tgz
```
### Import from a local file
Import to docker via pipe and `STDIN`.
```console
$ cat exampleimage.tgz | docker import - exampleimagelocal:new
```
Import with a commit message.
```console
$ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new
```
Import to docker from a local archive.
```console
$ docker import /path/to/exampleimage.tgz
```
### Import from a local directory
```console
$ sudo tar -c . | docker import - exampleimagedir
```
### Import from a local directory with new configurations
```console
$ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir
```
Note the `sudo` in this example – you must preserve
the ownership of the files (especially root ownership) during the
archiving with tar. If you are not root (or the sudo command) when you
tar, then the ownerships might not get preserved.
## When the daemon supports multiple operating systems
If the daemon supports multiple operating systems, and the image being imported
does not match the default operating system, it may be necessary to add
`--platform`. This would be necessary when importing a Linux image into a Windows
daemon.
```console
$ docker import --platform=linux .\linuximage.tar
```

130
docs/reference/commandline/index.md
View File

@ -20,72 +20,71 @@ read the [`dockerd`](dockerd.md) reference page.
### Docker management commands ### Docker management commands
| Command | Description | | Command | Description |
|:----------------------|:-----------------------------------------------------| | :-------------------------------- | :--------------------------------------------------- |
| [dockerd](dockerd.md) | Launch the Docker daemon | | [dockerd](dockerd.md) | Launch the Docker daemon |
| [info](info.md) | Display system-wide information | | [inspect](inspect.md) | Return low-level information on a container or image |
| [inspect](inspect.md) | Return low-level information on a container or image | | [system events](system_events.md) | Get real-time events from the server |
| [version](version.md) | Show the Docker version information | | [system info](system_info.md) | Display system-wide information |
| [version](version.md) | Show the Docker version information |
### Image commands ### Image commands
| Command | Description | | Command | Description |
|:------------------------------|:----------------------------------------------------------------| | :-------------------------------- | :-------------------------------------------------------------- |
| [build](build.md) | Build an image from a Dockerfile | | [image build](image_build.md) | Build an image from a Dockerfile |
| [commit](commit.md) | Create a new image from a container's changes | | [image commit](image_commit.md) | Create a new image from a container's changes |
| [history](history.md) | Show the history of an image | | [image history](image_history.md) | Show the history of an image |
| [images](images.md) | List images | | [image import](image_import.md) | Import the contents from a tarball to create a filesystem image |
| [import](import.md) | Import the contents from a tarball to create a filesystem image | | [image load](image_load.md) | Load an image from a tar archive or STDIN |
| [load](load.md) | Load an image from a tar archive or STDIN | | [image ls](image_ls.md) | List images |
| [image prune](image_prune.md) | Remove unused images | | [image prune](image_prune.md) | Remove unused images |
| [rmi](rmi.md) | Remove one or more images | | [image rm](image_rm.md) | Remove one or more images |
| [save](save.md) | Save images to a tar archive | | [image save](image_save.md) | Save images to a tar archive |
| [tag](tag.md) | Tag an image into a repository | | [image tag](image_tag.md) | Tag an image into a repository |
### Container commands ### Container commands
| Command | Description | | Command | Description |
|:--------------------------------------|:-----------------------------------------------------------------| | :---------------------------------------- | :-------------------------------------------------------------- |
| [attach](attach.md) | Attach to a running container | | [container attach](container_attach.md) | Attach to a running container |
| [container prune](container_prune.md) | Remove all stopped containers | | [container cp](container_cp.md) | Copy files/folders from a container to a HOSTDIR or to STDOUT |
| [cp](cp.md) | Copy files/folders from a container to a HOSTDIR or to STDOUT | | [container create](container_create.md) | Create a new container |
| [create](create.md) | Create a new container | | [container diff](container_diff.md) | Inspect changes on a container's filesystem |
| [diff](diff.md) | Inspect changes on a container's filesystem | | [container exec](container_exec.md) | Execute a command in a running container |
| [events](events.md) | Get real time events from the server | | [container export](container_export.md) | Export a container's filesystem as a tar archive |
| [exec](exec.md) | Execute a command in a running container | | [container kill](container_kill.md) | Kill a running container |
| [export](export.md) | Export a container's filesystem as a tar archive | | [container logs](container_logs.md) | Fetch the logs of a container |
| [kill](kill.md) | Kill a running container | | [container ls](container_ls.md) | List containers |
| [logs](logs.md) | Fetch the logs of a container | | [container pause](container_pause.md) | Pause all processes within a container |
| [pause](pause.md) | Pause all processes within a container | | [container port](container_port.md) | List port mappings or a specific mapping for the container |
| [port](port.md) | List port mappings or a specific mapping for the container | | [container prune](container_prune.md) | Remove all stopped containers |
| [ps](ps.md) | List containers | | [container rename](container_rename.md) | Rename a container |
| [rename](rename.md) | Rename a container | | [container restart](container_restart.md) | Restart a running container |
| [restart](restart.md) | Restart a running container | | [container rm](container_rm.md) | Remove one or more containers |
| [rm](rm.md) | Remove one or more containers | | [container run](container_run.md) | Create and run a new container from an image |
| [run](run.md) | Create and run a new container from an image | | [container start](container_start.md) | Start one or more stopped containers |
| [start](start.md) | Start one or more stopped containers | | [container stats](container_stats.md) | Display a live stream of container(s) resource usage statistics |
| [stats](stats.md) | Display a live stream of container(s) resource usage statistics | | [container stop](container_stop.md) | Stop a running container |
| [stop](stop.md) | Stop a running container | | [container top](container_top.md) | Display the running processes of a container |
| [top](top.md) | Display the running processes of a container | | [container unpause](container_unpause.md) | Unpause all processes within a container |
| [unpause](unpause.md) | Unpause all processes within a container | | [container update](container_update.md) | Update configuration of one or more containers |
| [update](update.md) | Update configuration of one or more containers | | [container wait](container_wait.md) | Block until a container stops, then print its exit code |
| [wait](wait.md) | Block until a container stops, then print its exit code |
### Hub and registry commands ### Hub and registry commands
| Command | Description | | Command | Description |
|:--------------------|:------------------------------------------------------------------------| | :------------------ | :-------------------------------- |
| [login](login.md) | Log in to a registry | | [login](login.md) | Log in to a registry |
| [logout](logout.md) | Log out from a registry | | [logout](logout.md) | Log out from a registry |
| [pull](pull.md) | Download an image from a registry | | [pull](pull.md) | Download an image from a registry |
| [push](push.md) | Upload an image to a registry | | [push](push.md) | Upload an image to a registry |
| [search](search.md) | Search Docker Hub for images | | [search](search.md) | Search Docker Hub for images |
### Network and connectivity commands ### Network and connectivity commands
| Command | Description | | Command | Description |
|:--------------------------------------------|:-------------------------------------------------------| | :------------------------------------------ | :----------------------------------------------------- |
| [network connect](network_connect.md) | Connect a container to a network | | [network connect](network_connect.md) | Connect a container to a network |
| [network create](network_create.md) | Create a new network | | [network create](network_create.md) | Create a new network |
| [network disconnect](network_disconnect.md) | Disconnect a container from a network | | [network disconnect](network_disconnect.md) | Disconnect a container from a network |
@ -97,7 +96,7 @@ read the [`dockerd`](dockerd.md) reference page.
### Shared data volume commands ### Shared data volume commands
| Command | Description | | Command | Description |
|:------------------------------------|:-----------------------------------------------------------------| | :---------------------------------- | :--------------------------------------------------------------- |
| [volume create](volume_create.md) | Creates a new volume where containers can consume and store data | | [volume create](volume_create.md) | Creates a new volume where containers can consume and store data |
| [volume inspect](volume_inspect.md) | Display information about a volume | | [volume inspect](volume_inspect.md) | Display information about a volume |
| [volume ls](volume_ls.md) | Lists all the volumes Docker knows about | | [volume ls](volume_ls.md) | Lists all the volumes Docker knows about |
@ -107,7 +106,7 @@ read the [`dockerd`](dockerd.md) reference page.
### Swarm node commands ### Swarm node commands
| Command | Description | | Command | Description |
|:--------------------------------|:--------------------------------------------------------------| | :------------------------------ | :------------------------------------------------------------ |
| [node demote](node_demote.md) | Demotes an existing manager so that it is no longer a manager | | [node demote](node_demote.md) | Demotes an existing manager so that it is no longer a manager |
| [node inspect](node_inspect.md) | Inspect a node in the swarm | | [node inspect](node_inspect.md) | Inspect a node in the swarm |
| [node ls](node_ls.md) | List nodes in the swarm | | [node ls](node_ls.md) | List nodes in the swarm |
@ -119,19 +118,19 @@ read the [`dockerd`](dockerd.md) reference page.
### Swarm management commands ### Swarm management commands
| Command | Description | | Command | Description |
|:----------------------------------------|:----------------------------------------------| | :-------------------------------------- | :-------------------------------------------- |
| [swarm init](swarm_init.md) | Initialize a swarm | | [swarm init](swarm_init.md) | Initialize a swarm |
| [swarm join-token](swarm_join-token.md) | Display or rotate join tokens |
| [swarm join](swarm_join.md) | Join a swarm as a manager node or worker node | | [swarm join](swarm_join.md) | Join a swarm as a manager node or worker node |
| [swarm leave](swarm_leave.md) | Remove the current node from the swarm | | [swarm leave](swarm_leave.md) | Remove the current node from the swarm |
| [swarm join-token](swarm_join-token.md) | Display or rotate join tokens |
| [swarm unlock](swarm_unlock.md) | Unlock swarm |
| [swarm unlock-key](swarm_unlock-key.md) | Manage the unlock key | | [swarm unlock-key](swarm_unlock-key.md) | Manage the unlock key |
| [swarm unlock](swarm_unlock.md) | Unlock swarm |
| [swarm update](swarm_update.md) | Update attributes of a swarm | | [swarm update](swarm_update.md) | Update attributes of a swarm |
### Swarm service commands ### Swarm service commands
| Command | Description | | Command | Description |
|:--------------------------------------|:----------------------------------------------------------------| | :------------------------------------ | :-------------------------------------------------------------- |
| [service create](service_create.md) | Create a new service | | [service create](service_create.md) | Create a new service |
| [service inspect](service_inspect.md) | Inspect a service | | [service inspect](service_inspect.md) | Inspect a service |
| [service logs](service_logs.md) | Fetch the logs of a service or task | | [service logs](service_logs.md) | Fetch the logs of a service or task |
@ -144,7 +143,7 @@ read the [`dockerd`](dockerd.md) reference page.
### Swarm secret commands ### Swarm secret commands
| Command | Description | | Command | Description |
|:-------------------------------------|:------------------------------------------------| | :----------------------------------- | :---------------------------------------------- |
| [secret create](secret_create.md) | Create a secret from a file or STDIN as content | | [secret create](secret_create.md) | Create a secret from a file or STDIN as content |
| [secret inspect](service_inspect.md) | Inspect the specified secret | | [secret inspect](service_inspect.md) | Inspect the specified secret |
| [secret ls](secret_ls.md) | List secrets in the swarm | | [secret ls](secret_ls.md) | List secrets in the swarm |
@ -153,18 +152,18 @@ read the [`dockerd`](dockerd.md) reference page.
### Swarm stack commands ### Swarm stack commands
| Command | Description | | Command | Description |
|:------------------------------------|:--------------------------------------------------------| | :---------------------------------- | :------------------------------------------------------ |
| [stack config](stack_config.md) | Output the Compose file after merges and interpolations |
| [stack deploy](stack_deploy.md) | Deploy a new stack or update an existing stack | | [stack deploy](stack_deploy.md) | Deploy a new stack or update an existing stack |
| [stack ls](stack_ls.md) | List stacks in the swarm | | [stack ls](stack_ls.md) | List stacks in the swarm |
| [stack ps](stack_ps.md) | List the tasks in the stack | | [stack ps](stack_ps.md) | List the tasks in the stack |
| [stack rm](stack_rm.md) | Remove the stack from the swarm | | [stack rm](stack_rm.md) | Remove the stack from the swarm |
| [stack services](stack_services.md) | List the services in the stack | | [stack services](stack_services.md) | List the services in the stack |
| [stack config](stack_config.md) | Output the Compose file after merges and interpolations |
### Plugin commands ### Plugin commands
| Command | Description | | Command | Description |
|:------------------------------------|:------------------------------------------------| | :---------------------------------- | :---------------------------------------------- |
| [plugin create](plugin_create.md) | Create a plugin from a rootfs and configuration | | [plugin create](plugin_create.md) | Create a plugin from a rootfs and configuration |
| [plugin disable](plugin_disable.md) | Disable a plugin | | [plugin disable](plugin_disable.md) | Disable a plugin |
| [plugin enable](plugin_enable.md) | Enable a plugin | | [plugin enable](plugin_enable.md) | Enable a plugin |
@ -178,13 +177,12 @@ read the [`dockerd`](dockerd.md) reference page.
### Context commands ### Context commands
| Command | Description | | Command | Description |
|:--------------------------------------|:-------------------------------| | :------------------------------------ | :----------------------------- |
| [context create](context_create.md) | Create a context | | [context create](context_create.md) | Create a context |
| [context export](context_export.md) | Export a context | | [context export](context_export.md) | Export a context |
| [context import](context_import.md) | Import a context | | [context import](context_import.md) | Import a context |
| [context inspect](context_inspect.md) | Inspect one or more contexts |
| [context ls](context_ls.md) | List contexts | | [context ls](context_ls.md) | List contexts |
| [context rm](context_rm.md) | Remove one or more contexts | | [context rm](context_rm.md) | Remove one or more contexts |
| [context update](context_update.md) | Update a context | | [context update](context_update.md) | Update a context |
| [context use](context_use.md) | Set the current docker context | | [context use](context_use.md) | Set the current docker context |
| [context inspect](context_inspect.md) | Inspect one or more contexts |

167
docs/reference/commandline/info.md
View File

@ -1,4 +1,4 @@
# info # docker info
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Display system-wide information Display system-wide information
@ -9,169 +9,10 @@ Display system-wide information
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`-f`](#format), [`--format`](#format) | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | `-f`, `--format` | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
This command displays system wide information regarding the Docker installation.
Information displayed includes the kernel version, number of containers and images.
The number of images shown is the number of unique images. The same image tagged
under different names is counted only once.
If a format is specified, the given template will be executed instead of the
default format. Go's [text/template](https://pkg.go.dev/text/template) package
describes all the details of the format.
Depending on the storage driver in use, additional information can be shown, such
as pool name, data file, metadata file, data space used, total data space, metadata
space used, and total metadata space.
The data file is where the images are stored and the metadata file is where the
meta data regarding those images are stored. When run for the first time Docker
allocates a certain amount of data space and meta data space from the space
available on the volume where `/var/lib/docker` is mounted.
## Examples
### Show output
The example below shows the output for a daemon running on Ubuntu Linux,
using the `overlay2` storage driver. As can be seen in the output, additional
information about the `overlay2` storage driver is shown:
```console
$ docker info
Client: Docker Engine - Community
Version: 24.0.0
Context: default
Debug Mode: false
Plugins:
buildx: Docker Buildx (Docker Inc.)
Version: v0.10.4
Path: /usr/libexec/docker/cli-plugins/docker-buildx
compose: Docker Compose (Docker Inc.)
Version: v2.17.2
Path: /usr/libexec/docker/cli-plugins/docker-compose
Server:
Containers: 14
Running: 3
Paused: 1
Stopped: 10
Images: 52
Server Version: 23.0.3
Storage Driver: overlay2
Backing Filesystem: extfs
Supports d_type: true
Using metacopy: false
Native Overlay Diff: true
userxattr: false
Logging Driver: json-file
Cgroup Driver: systemd
Cgroup Version: 2
Plugins:
Volume: local
Network: bridge host ipvlan macvlan null overlay
Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
CDI spec directories:
/etc/cdi
/var/run/cdi
Swarm: inactive
Runtimes: io.containerd.runc.v2 runc
Default Runtime: runc
Init Binary: docker-init
containerd version: 2806fc1057397dbaeefbea0e4e17bddfbd388f38
runc version: v1.1.5-0-gf19387a
init version: de40ad0
Security Options:
apparmor
seccomp
Profile: builtin
cgroupns
Kernel Version: 5.15.0-25-generic
Operating System: Ubuntu 22.04 LTS
OSType: linux
Architecture: x86_64
CPUs: 1
Total Memory: 991.7 MiB
Name: ip-172-30-0-91.ec2.internal
ID: 4cee4408-10d2-4e17-891c-a41736ac4536
Docker Root Dir: /var/lib/docker
Debug Mode: false
Username: gordontheturtle
Experimental: false
Insecure Registries:
myinsecurehost:5000
127.0.0.0/8
Live Restore Enabled: false
```
### <a name="format"></a> Format the output (--format)
You can also specify the output format:
```console
$ docker info --format '{{json .}}'
{"ID":"4cee4408-10d2-4e17-891c-a41736ac4536","Containers":14, ...}
```
### Run `docker info` on Windows
Here is a sample output for a daemon running on Windows Server:
```console
C:\> docker info
Client: Docker Engine - Community
Version: 24.0.0
Context: default
Debug Mode: false
Plugins:
buildx: Docker Buildx (Docker Inc.)
Version: v0.10.4
Path: C:\Program Files\Docker\cli-plugins\docker-buildx.exe
compose: Docker Compose (Docker Inc.)
Version: v2.17.2
Path: C:\Program Files\Docker\cli-plugins\docker-compose.exe
Server:
Containers: 1
Running: 0
Paused: 0
Stopped: 1
Images: 17
Server Version: 23.0.3
Storage Driver: windowsfilter
Logging Driver: json-file
Plugins:
Volume: local
Network: ics internal l2bridge l2tunnel nat null overlay private transparent
Log: awslogs etwlogs fluentd gcplogs gelf json-file local splunk syslog
Swarm: inactive
Default Isolation: process
Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500)
Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707)
OSType: windows
Architecture: x86_64
CPUs: 8
Total Memory: 3.999 GiB
Name: WIN-V0V70C0LU5P
ID: 2880d38d-464e-4d01-91bd-c76f33ba3981
Docker Root Dir: C:\ProgramData\docker
Debug Mode: false
Experimental: true
Insecure Registries:
myregistry:5000
127.0.0.0/8
Registry Mirrors:
http://192.168.1.2/
http://registry-mirror.example.com:5000/
Live Restore Enabled: false
```

64
docs/reference/commandline/kill.md
View File

@ -1,4 +1,4 @@
# kill # docker kill
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Kill one or more running containers Kill one or more running containers
@ -9,66 +9,10 @@ Kill one or more running containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:--------------------------------| |:-----------------|:---------|:--------|:--------------------------------|
| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container | | `-s`, `--signal` | `string` | | Signal to send to the container |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker kill` subcommand kills one or more containers. The main process
inside the container is sent `SIGKILL` signal (default), or the signal that is
specified with the `--signal` option. You can reference a container by its
ID, ID-prefix, or name.
The `--signal` flag sets the system call signal that is sent to the container.
This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGINT`,
or an unsigned number that matches a position in the kernel's syscall table,
for instance `2`.
While the default (`SIGKILL`) signal will terminate the container, the signal
set through `--signal` may be non-terminal, depending on the container's main
process. For example, the `SIGHUP` signal in most cases will be non-terminal,
and the container will continue running after receiving the signal.
> **Note**
>
> `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of
> `/bin/sh -c`, which does not pass signals. This means that the executable is
> not the container’s PID 1 and does not receive Unix signals.
## Examples
### Send a KILL signal to a container
The following example sends the default `SIGKILL` signal to the container named
`my_container`:
```console
$ docker kill my_container
```
### <a name="signal"></a> Send a custom signal to a container (--signal)
The following example sends a `SIGHUP` signal to the container named
`my_container`:
```console
$ docker kill --signal=SIGHUP my_container
```
You can specify a custom signal either by _name_, or _number_. The `SIG` prefix
is optional, so the following examples are equivalent:
```console
$ docker kill --signal=SIGHUP my_container
$ docker kill --signal=HUP my_container
$ docker kill --signal=1 my_container
```
Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html)
man-page for a list of standard Linux signals.

51
docs/reference/commandline/load.md
View File

@ -1,4 +1,4 @@
# load # docker load
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Load an image from a tar archive or STDIN Load an image from a tar archive or STDIN
@ -9,52 +9,11 @@ Load an image from a tar archive or STDIN
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:------------------------------------|:---------|:--------|:---------------------------------------------| |:----------------|:---------|:--------|:---------------------------------------------|
| [`-i`](#input), [`--input`](#input) | `string` | | Read from tar archive file, instead of STDIN | | `-i`, `--input` | `string` | | Read from tar archive file, instead of STDIN |
| `-q`, `--quiet` | | | Suppress the load output | | `-q`, `--quiet` | | | Suppress the load output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
Load an image or repository from a tar archive (even if compressed with gzip,
bzip2, xz or zstd) from a file or STDIN. It restores both images and tags.
## Examples
```console
$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
```
### Load images from STDIN
```console
$ docker load < busybox.tar.gz
Loaded image: busybox:latest
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox latest 769b9341d937 7 weeks ago 2.489 MB
```
### <a name="input"></a> Load images from a file (--input)
```console
$ docker load --input fedora.tar
Loaded image: fedora:rawhide
Loaded image: fedora:20
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox latest 769b9341d937 7 weeks ago 2.489 MB
fedora rawhide 0d20aec6529d 7 weeks ago 387 MB
fedora 20 58394af37342 7 weeks ago 385.5 MB
fedora heisenbug 58394af37342 7 weeks ago 385.5 MB
fedora latest 58394af37342 7 weeks ago 385.5 MB
```

54
docs/reference/commandline/logs.md
View File

@ -1,4 +1,4 @@
# logs # docker logs
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Fetch the logs of a container Fetch the logs of a container
@ -16,58 +16,8 @@ Fetch the logs of a container
| `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | | `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
| `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs | | `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs |
| `-t`, `--timestamps` | | | Show timestamps | | `-t`, `--timestamps` | | | Show timestamps |
| [`--until`](#until) | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | | `--until` | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker logs` command batch-retrieves logs present at the time of execution.
For more information about selecting and configuring logging drivers, refer to
[Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/).
The `docker logs --follow` command will continue streaming the new output from
the container's `STDOUT` and `STDERR`.
Passing a negative number or a non-integer to `--tail` is invalid and the
value is set to `all` in that case.
The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://pkg.go.dev/time#RFC3339Nano)
, for example `2014-09-16T06:17:46.000000000Z`, to each
log entry. To ensure that the timestamps are aligned the
nano-second part of the timestamp will be padded with zero when necessary.
The `docker logs --details` command will add on extra attributes, such as
environment variables and labels, provided to `--log-opt` when creating the
container.
The `--since` option shows only the container logs generated after
a given date. You can specify the date as an RFC 3339 date, a UNIX
timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date
format you may also use RFC3339Nano, `2006-01-02T15:04:05`,
`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
timezone on the client 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. You can combine the
`--since` option with either or both of the `--follow` or `--tail` options.
## Examples
### <a name="until"></a> Retrieve logs until a specific point in time (--until)
In order to retrieve logs before a specific point in time, run:
```console
$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
$ date
Tue 14 Nov 2017 16:40:00 CET
$ docker logs -f --until=2s test
Tue 14 Nov 2017 16:40:00 CET
Tue 14 Nov 2017 16:40:01 CET
Tue 14 Nov 2017 16:40:02 CET
```

24
docs/reference/commandline/pause.md
View File

@ -1,4 +1,4 @@
# pause # docker pause
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Pause all processes within one or more containers Pause all processes within one or more containers
@ -10,25 +10,3 @@ Pause all processes within one or more containers
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker pause` command suspends all processes in the specified containers.
On Linux, this uses the freezer cgroup. Traditionally, when suspending a process
the `SIGSTOP` signal is used, which is observable by the process being suspended.
With the freezer cgroup the process is unaware, and unable to capture,
that it is being suspended, and subsequently resumed. On Windows, only Hyper-V
containers can be paused.
See the
[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
for further details.
## Examples
```console
$ docker pause my_container
```
## Related commands
* [unpause](unpause.md)

32
docs/reference/commandline/port.md
View File

@ -1,4 +1,4 @@
# port # docker port
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
List port mappings or a specific mapping for the container List port mappings or a specific mapping for the container
@ -10,33 +10,3 @@ List port mappings or a specific mapping for the container
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Examples
### Show all mapped ports
You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or
just a specific mapping:
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test
$ docker port test
7890/tcp -> 0.0.0.0:4321
9876/tcp -> 0.0.0.0:1234
$ docker port test 7890/tcp
0.0.0.0:4321
$ docker port test 7890/udp
2014/06/24 11:53:36 Error: No public port '7890/udp' published for test
$ docker port test 7890
0.0.0.0:4321
```

445
docs/reference/commandline/ps.md
View File

@ -1,4 +1,4 @@
# ps # docker ps
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
List containers List containers
@ -9,440 +9,17 @@ List containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`-a`](#all), [`--all`](#all) | | | Show all containers (default shows just running) | | `-a`, `--all` | | | Show all containers (default shows just running) |
| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | | `-f`, `--filter` | `filter` | | Filter output based on conditions provided |
| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) | | `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) |
| `-l`, `--latest` | | | Show the latest created container (includes all states) | | `-l`, `--latest` | | | Show the latest created container (includes all states) |
| [`--no-trunc`](#no-trunc) | | | Don't truncate output | | `--no-trunc` | | | Don't truncate output |
| `-q`, `--quiet` | | | Only display container IDs | | `-q`, `--quiet` | | | Only display container IDs |
| [`-s`](#size), [`--size`](#size) | | | Display total file sizes | | `-s`, `--size` | | | Display total file sizes |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Examples
### <a name="no-trunc"></a> Do not truncate output (--no-trunc)
Running `docker ps --no-trunc` showing 2 linked containers.
```console
$ docker ps --no-trunc
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ca5534a51dd04bbcebe9b23ba05f389466cf0c190f1f8f182d7eea92a9671d00 ubuntu:22.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp
9ca9747b233100676a48cc7806131586213fa5dab86dd1972d6a8732e3a84a4d crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db
```
### <a name="all"></a> Show both running and stopped containers (-a, --all)
The `docker ps` command only shows running containers by default. To see all
containers, use the `--all` (or `-a`) flag:
```console
$ docker ps -a
```
`docker ps` groups exposed ports into a single range if possible. E.g., a
container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in
the `PORTS` column.
### <a name="size"></a> Show disk usage by container (--size)
The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container:
```console
$ docker ps --size
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE
e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB)
00c6131c5e30 telegraf:1.5 "/entrypoint.sh" 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB)
```
* The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container
* The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer.
For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section.
### <a name="filter"></a> Filtering (--filter)
The `--filter` (or `-f`) flag format is a `key=value` pair. If there is more
than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
The currently supported filters are:
| Filter | Description |
|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------|
| `id` | Container's ID |
| `name` | Container's name |
| `label` | An arbitrary string representing either a key or a key-value pair. Expressed as `<key>` or `<key>=<value>` |
| `exited` | An integer representing the container's exit code. Only useful with `--all`. |
| `status` | One of `created`, `restarting`, `running`, `removing`, `paused`, `exited`, or `dead` |
| `ancestor` | Filters containers which share a given image as an ancestor. Expressed as `<image-name>[:<tag>]`, `<image id>`, or `<image@digest>` |
| `before` or `since` | Filters containers created before or after a given container ID or name |
| `volume` | Filters running containers which have mounted a given volume or bind mount. |
| `network` | Filters running containers connected to a given network. |
| `publish` or `expose` | Filters containers which publish or expose a given port. Expressed as `<port>[/<proto>]` or `<startport-endport>/[<proto>]` |
| `health` | Filters containers based on their healthcheck status. One of `starting`, `healthy`, `unhealthy` or `none`. |
| `isolation` | Windows daemon only. One of `default`, `process`, or `hyperv`. |
| `is-task` | Filters containers that are a "task" for a service. Boolean option (`true` or `false`) |
#### label
The `label` filter matches containers based on the presence of a `label` alone or a `label` and a
value.
The following filter matches containers with the `color` label regardless of its value.
```console
$ docker ps --filter "label=color"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley
d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani
```
The following filter matches containers with the `color` label with the `blue` value.
```console
$ docker ps --filter "label=color=blue"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani
```
#### name
The `name` filter matches on all or part of a container's name.
The following filter matches all containers with a name containing the `nostalgic_stallman` string.
```console
$ docker ps --filter "name=nostalgic_stallman"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman
```
You can also filter for a substring in a name as this shows:
```console
$ docker ps --filter "name=nostalgic"
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
715ebfcee040 busybox "top" 3 seconds ago Up 1 second i_am_nostalgic
9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman
673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley
```
#### exited
The `exited` filter matches containers by exist status code. For example, to
filter for containers that have exited successfully:
```console
$ docker ps -a --filter 'exited=0'
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey
106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani
48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds
```
#### Filter by exit signal
You can use a filter to locate containers that exited with status of `137`
meaning a `SIGKILL(9)` killed them.
```console
$ docker ps -a --filter 'exited=137'
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski
a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande
```
Any of these events result in a `137` status:
* the `init` process of the container is killed manually
* `docker kill` kills the container
* Docker daemon restarts which kills all running containers
#### status
The `status` filter matches containers by status. The possible values for the container status are:
| Status | Description |
| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created` | A container that has never been started. |
| `running` | A running container, started by either `docker start` or `docker run`. |
| `paused` | A paused container. See `docker pause`. |
| `restarting` | A container which is starting due to the designated restart policy for that container. |
| `exited` | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the `docker stop` command. |
| `removing` | A container which is in the process of being removed. See `docker rm`. |
| `dead` | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. `dead` containers cannot be (re)started, only removed. |
For example, to filter for `running` containers:
```console
$ docker ps --filter status=running
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic
d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top
9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman
```
To filter for `paused` containers:
```console
$ docker ps --filter status=paused
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley
```
#### ancestor
The `ancestor` filter matches containers based on its image or a descendant of
it. The filter supports the following image representation:
- `image`
- `image:tag`
- `image:tag@digest`
- `short-id`
- `full-id`
If you don't specify a `tag`, the `latest` tag is used. For example, to filter
for containers that use the latest `ubuntu` image:
```console
$ docker ps --filter ancestor=ubuntu
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet
82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose
bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath
```
Match containers based on the `ubuntu-c1` image which, in this case, is a child
of `ubuntu`:
```console
$ docker ps --filter ancestor=ubuntu-c1
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
```
Match containers based on the `ubuntu` version `22.04` image:
```console
$ docker ps --filter ancestor=ubuntu:22.04
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose
```
The following matches containers based on the layer `d0e008c6cf02` or an image
that have this layer in its layer stack.
```console
$ docker ps --filter ancestor=d0e008c6cf02
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose
```
#### Create time
##### before
The `before` filter shows only containers created before the container with
a given ID or name. For example, having these containers created:
```console
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky
4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat
```
Filtering with `before` would give:
```console
$ docker ps -f before=9c3527ed70ce
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat
```
##### since
The `since` filter shows only containers created since the container with a given
ID or name. For example, with the same containers as in `before` filter:
```console
$ docker ps -f since=6e63f6ff38b0
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky
4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton
```
#### volume
The `volume` filter shows only containers that mount a specific volume or have
a volume mounted in a specific path:
```console
$ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}"
CONTAINER ID MOUNTS
9c3527ed70ce remote-volume
$ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}"
CONTAINER ID MOUNTS
9c3527ed70ce remote-volume
```
#### network
The `network` filter shows only containers that are connected to a network with
a given name or ID.
The following filter matches all containers that are connected to a network
with a name containing `net1`.
```console
$ docker run -d --net=net1 --name=test1 ubuntu top
$ docker run -d --net=net2 --name=test2 ubuntu top
$ docker ps --filter network=net1
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1
```
The network filter matches on both the network's name and ID. The following
example shows all containers that are attached to the `net1` network, using
the network ID as a filter:
```console
$ docker network inspect --format "{{.ID}}" net1
8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5
$ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1
```
#### publish and expose
The `publish` and `expose` filters show only containers that have published or exposed port with a given port
number, port range, and/or protocol. The default protocol is `tcp` when not specified.
The following filter matches all containers that have published port of 80:
```console
$ docker run -d --publish=80 busybox top
$ docker run -d --expose=8080 busybox top
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy
fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen
$ 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
```
The following filter matches all containers that have exposed TCP port in the range of `8000-8080`:
```console
$ 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
```
The following filter matches all containers that have exposed UDP port `80`:
```console
$ docker ps --filter publish=80/udp
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) pretty-prints container output using a Go
template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|:--------------|:------------------------------------------------------------------------------------------------|
| `.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. |
| `.State` | Container status (for example; "created", "running", "exited"). |
| `.Status` | Container status with details about duration and health-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 `'{{.Label "com.docker.swarm.cpu"}}'` |
| `.Mounts` | Names of the volumes mounted in this container. |
| `.Networks` | Names of the networks attached to this container. |
When using the `--format` option, the `ps` command will either output the data
exactly as the template declares or, when using the `table` directive, includes
column headers as well.
The following example uses a template without headers and outputs the `ID` and
`Command` entries separated by a colon (`:`) for all running containers:
```console
$ docker ps --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
```
To list all running containers with their labels in a table format you can use:
```console
$ docker ps --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
```
To list all running containers in JSON format, use the `json` directive:
```console
$ docker ps --format json
{"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"}
```

237
docs/reference/commandline/pull.md
View File

@ -1,4 +1,4 @@
# pull # docker pull
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Download an image from a registry Download an image from a registry
@ -9,236 +9,13 @@ Download an image from a registry
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------------|:---------|:--------|:-------------------------------------------------| |:--------------------------|:---------|:--------|:-------------------------------------------------|
| [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Download all tagged images in the repository | | `-a`, `--all-tags` | | | Download all tagged images in the repository |
| `--disable-content-trust` | | | Skip image verification | | `--disable-content-trust` | | | Skip image verification |
| `--platform` | `string` | | Set platform if server is multi-platform capable | | `--platform` | `string` | | Set platform if server is multi-platform capable |
| `-q`, `--quiet` | | | Suppress verbose output | | `-q`, `--quiet` | | | Suppress verbose output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
Most of your images will be created on top of a base image from the
[Docker Hub](https://hub.docker.com) registry.
[Docker Hub](https://hub.docker.com) contains many pre-built images that you
can `pull` and try without needing to define and configure your own.
To download a particular image, or set of images (i.e., a repository),
use `docker pull`.
### Proxy configuration
If you are behind an HTTP proxy server, for example in corporate settings,
before open a connect to registry, you may need to configure the Docker
daemon's proxy settings, refer to the [dockerd command-line reference](dockerd.md#proxy-configuration)
for details.
### Concurrent downloads
By default the Docker daemon will pull three layers of an image at a time.
If you are on a low bandwidth connection this may cause timeout issues and you may want to lower
this via the `--max-concurrent-downloads` daemon option. See the
[daemon documentation](dockerd.md) for more details.
## Examples
### Pull an image from Docker Hub
To download a particular image, or set of images (i.e., a repository), use
`docker image pull` (or the `docker pull` shorthand). If no tag is provided,
Docker Engine uses the `:latest` tag as a default. This example pulls the
`debian:latest` image:
```console
$ docker image pull debian
Using default tag: latest
latest: Pulling from library/debian
e756f3fdd6a3: Pull complete
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:latest
docker.io/library/debian:latest
```
Docker images can consist of multiple layers. In the example above, the image
consists of a single layer; `e756f3fdd6a3`.
Layers can be reused by images. For example, the `debian:bookworm` image shares
its layer with the `debian:latest`. Pulling the `debian:bookworm` image therefore
only pulls its metadata, but not its layers, because the layer is already present
locally:
```console
$ docker image pull debian:bookworm
bookworm: Pulling from library/debian
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm
```
To see which images are present locally, use the [`docker images`](images.md)
command:
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
debian bookworm 4eacea30377a 8 days ago 124MB
debian latest 4eacea30377a 8 days ago 124MB
```
Docker uses a content-addressable image store, and the image ID is a SHA256
digest covering the image's configuration and layers. In the example above,
`debian:bookworm` and `debian:latest` have the same image ID because they are
the same image tagged with different names. Because they are the same image,
their layers are stored only once and do not consume extra disk space.
For more information about images, layers, and the content-addressable store,
refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/).
### Pull an image by digest (immutable identifier)
So far, you've pulled images by their name (and "tag"). Using names and tags is
a convenient way to work with images. When using tags, you can `docker pull` an
image again to make sure you have the most up-to-date version of that image.
For example, `docker pull ubuntu:22.04` pulls the latest version of the Ubuntu
22.04 image.
In some cases you don't want images to be updated to newer versions, but prefer
to use a fixed version of an image. Docker enables you to pull an image by its
digest. When pulling an image by digest, you specify exactly which version
of an image to pull. Doing so, allows you to "pin" an image to that version,
and guarantee that the image you're using is always the same.
To know the digest of an image, pull the image first. Let's pull the latest
`ubuntu:22.04` image from Docker Hub:
```console
$ docker pull ubuntu:22.04
22.04: Pulling from library/ubuntu
125a6e411906: Pull complete
Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
Status: Downloaded newer image for ubuntu:22.04
docker.io/library/ubuntu:22.04
```
Docker prints the digest of the image after the pull has finished. In the example
above, the digest of the image is:
```console
sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
```
Docker also prints the digest of an image when pushing to a registry. This
may be useful if you want to pin to a version of the image you just pushed.
A digest takes the place of the tag when pulling an image, for example, to
pull the above image by digest, run the following command:
```console
$ docker pull ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d: Pulling from library/ubuntu
Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
Status: Image is up to date for ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
```
Digest can also be used in the `FROM` of a Dockerfile, for example:
```dockerfile
FROM ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d
LABEL org.opencontainers.image.authors="some maintainer <maintainer@example.com>"
```
> **Note**
>
> Using this feature "pins" an image to a specific version in time.
> Docker does therefore not pull updated versions of an image, which may include
> security updates. If you want to pull an updated image, you need to change the
> digest accordingly.
### Pull from a different registry
By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to
manually specify the path of a registry to pull from. For example, if you have
set up a local registry, you can specify its path to pull from it. A registry
path is similar to a URL, but does not contain a protocol specifier (`https://`).
The following command pulls the `testing/test-image` image from a local registry
listening on port 5000 (`myregistry.local:5000`):
```console
$ docker image pull myregistry.local:5000/testing/test-image
```
Registry credentials are managed by [docker login](login.md).
Docker uses the `https://` protocol to communicate with a registry, unless the
registry is allowed to be accessed over an insecure connection. Refer to the
[insecure registries](dockerd.md#insecure-registries) section for more information.
### <a name="all-tags"></a> Pull a repository with multiple images (-a, --all-tags)
By default, `docker pull` pulls a single image from the registry. A repository
can contain multiple images. To pull all images from a repository, provide the
`-a` (or `--all-tags`) option when using `docker pull`.
This command pulls all images from the `ubuntu` repository:
```console
$ docker image pull --all-tags ubuntu
Pulling repository ubuntu
ad57ef8d78d7: Download complete
105182bb5e8b: Download complete
511136ea3c5a: Download complete
73bd853d2ea5: Download complete
....
Status: Downloaded newer image for ubuntu
```
After the pull has completed use the `docker image ls` command (or the `docker images`
shorthand) to see the images that were pulled. The example below shows all the
`ubuntu` images that are present locally:
```console
$ docker image ls --filter reference=ubuntu
REPOSITORY TAG IMAGE ID CREATED SIZE
ubuntu 18.04 c6ad7e71ba7d 5 weeks ago 63.2MB
ubuntu bionic c6ad7e71ba7d 5 weeks ago 63.2MB
ubuntu 22.04 5ccefbfc0416 2 months ago 78MB
ubuntu focal ff0fea8310f3 2 months ago 72.8MB
ubuntu latest ff0fea8310f3 2 months ago 72.8MB
ubuntu jammy 41ba606c8ab9 3 months ago 79MB
ubuntu 20.04 ba6acccedd29 7 months ago 72.8MB
```
### Cancel a pull
Killing the `docker pull` process, for example by pressing `CTRL-c` while it is
running in a terminal, will terminate the pull operation.
```console
$ docker pull ubuntu
Using default tag: latest
latest: Pulling from library/ubuntu
a3ed95caeb02: Pulling fs layer
236608c7b546: Pulling fs layer
^C
```
The Engine terminates a pull operation when the connection between the daemon
and the client (initiating the pull) is cut or lost for any reason or the
command is manually terminated.

114
docs/reference/commandline/push.md
View File

@ -1,4 +1,4 @@
# push # docker push
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Upload an image to a registry Upload an image to a registry
@ -9,114 +9,12 @@ Upload an image to a registry
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------------|:-----|:--------|:--------------------------------------------| |:--------------------------|:-----|:--------|:--------------------------------------------|
| [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Push all tags of an image to the repository | | `-a`, `--all-tags` | | | Push all tags of an image to the repository |
| `--disable-content-trust` | | | Skip image signing | | `--disable-content-trust` | | | Skip image signing |
| `-q`, `--quiet` | | | Suppress verbose output | | `-q`, `--quiet` | | | Suppress verbose output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
Use `docker image push` to share your images to the [Docker Hub](https://hub.docker.com)
registry or to a self-hosted one.
Refer to the [`docker image tag`](tag.md) reference for more information about valid
image and tag names.
Killing the `docker image push` process, for example by pressing `CTRL-c` while it is
running in a terminal, terminates the push operation.
Progress bars are shown during docker push, which show the uncompressed size.
The actual amount of data that's pushed will be compressed before sending, so
the uploaded size will not be reflected by the progress bar.
Registry credentials are managed by [docker login](login.md).
### Concurrent uploads
By default the Docker daemon will push five layers of an image at a time.
If you are on a low bandwidth connection this may cause timeout issues and you may want to lower
this via the `--max-concurrent-uploads` daemon option. See the
[daemon documentation](dockerd.md) for more details.
## Examples
### Push a new image to a registry
First save the new image by finding the container ID (using [`docker container ls`](ps.md))
and then committing it to a new image name. Note that only `a-z0-9-_.` are
allowed when naming images:
```console
$ docker container commit c16378f943fe rhel-httpd:latest
```
Now, push the image to the registry using the image ID. In this example the
registry is on host named `registry-host` and listening on port `5000`. To do
this, tag the image with the host name or IP address, and the port of the
registry:
```console
$ docker image tag rhel-httpd:latest registry-host:5000/myadmin/rhel-httpd:latest
$ docker image push registry-host:5000/myadmin/rhel-httpd:latest
```
Check that this worked by running:
```console
$ docker image ls
```
You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd`
listed.
### <a name="all-tags"></a> Push all tags of an image (-a, --all-tags)
Use the `-a` (or `--all-tags`) option to push all tags of a local image.
The following example creates multiple tags for an image, and pushes all those
tags to Docker Hub.
```console
$ docker image tag myimage registry-host:5000/myname/myimage:latest
$ docker image tag myimage registry-host:5000/myname/myimage:v1.0.1
$ docker image tag myimage registry-host:5000/myname/myimage:v1.0
$ docker image tag myimage registry-host:5000/myname/myimage:v1
```
The image is now tagged under multiple names:
```console
$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage v1 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage v1.0 6d5fcfe5ff17 2 hours ago 1.22MB
registry-host:5000/myname/myimage v1.0.1 6d5fcfe5ff17 2 hours ago 1.22MB
```
When pushing with the `--all-tags` option, all tags of the `registry-host:5000/myname/myimage`
image are pushed:
```console
$ docker image push --all-tags registry-host:5000/myname/myimage
The push refers to repository [registry-host:5000/myname/myimage]
195be5f8be1d: Pushed
latest: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1.0: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1.0.1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
```

11
docs/reference/commandline/rename.md
View File

@ -1,4 +1,4 @@
# rename # docker rename
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Rename a container Rename a container
@ -10,12 +10,3 @@ Rename a container
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker rename` command renames a container.
## Examples
```console
$ docker rename my_container my_new_container
```

7
docs/reference/commandline/restart.md
View File

@ -1,4 +1,4 @@
# restart # docker restart
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Restart one or more containers Restart one or more containers
@ -17,8 +17,3 @@ Restart one or more containers
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Examples
```console
$ docker restart my_container
```

102
docs/reference/commandline/rm.md
View File

@ -1,4 +1,4 @@
# rm # docker rm
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Remove one or more containers Remove one or more containers
@ -9,102 +9,12 @@ Remove one or more containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:------------------------------------------|:-----|:--------|:--------------------------------------------------------| |:------------------|:-----|:--------|:--------------------------------------------------------|
| [`-f`](#force), [`--force`](#force) | | | Force the removal of a running container (uses SIGKILL) | | `-f`, `--force` | | | Force the removal of a running container (uses SIGKILL) |
| [`-l`](#link), [`--link`](#link) | | | Remove the specified link | | `-l`, `--link` | | | Remove the specified link |
| [`-v`](#volumes), [`--volumes`](#volumes) | | | Remove anonymous volumes associated with the container | | `-v`, `--volumes` | | | Remove anonymous volumes associated with the container |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Examples
### Remove a container
This removes the container referenced under the link `/redis`.
```console
$ docker rm /redis
/redis
```
### <a name="link"></a> Remove a link specified with `--link` on the default bridge network (--link)
This removes the underlying link between `/webapp` and the `/redis`
containers on the default bridge network, removing all network communication
between the two containers. This does not apply when `--link` is used with
user-specified networks.
```console
$ docker rm --link /webapp/redis
/webapp/redis
```
### <a name="force"></a> Force-remove a running container (--force)
This command force-removes a running container.
```console
$ docker rm --force redis
redis
```
The main process inside the container referenced under the link `redis` will receive
`SIGKILL`, then the container will be removed.
### Remove all stopped containers
Use the [`docker container prune`](container_prune.md) command to remove all
stopped containers, or refer to the [`docker system prune`](system_prune.md)
command to remove unused containers in addition to other Docker resources, such
as (unused) images and networks.
Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to
generate a list of container IDs to remove, and use that list as argument for
the `docker rm` command.
Combining commands can be more flexible, but is less portable as it depends
on features provided by the shell, and the exact syntax may differ depending on
what shell is used. To use this approach on Windows, consider using PowerShell
or Bash.
The example below uses `docker ps -q` to print the IDs of all containers that
have exited (`--filter status=exited`), and removes those containers with
the `docker rm` command:
```console
$ docker rm $(docker ps --filter status=exited -q)
```
Or, using the `xargs` Linux utility:
```console
$ docker ps --filter status=exited -q | xargs docker rm
```
### <a name="volumes"></a> Remove a container and its volumes (-v, --volumes)
```console
$ docker rm --volumes redis
redis
```
This command removes the container and any volumes associated with it.
Note that if a volume was specified with a name, it will not be removed.
### Remove a container and selectively remove volumes
```console
$ docker create -v awesome:/foo -v /bar --name hello redis
hello
$ docker rm -v hello
```
In this example, the volume for `/foo` remains intact, but the volume for
`/bar` is removed. The same behavior holds for volumes inherited with
`--volumes-from`.

90
docs/reference/commandline/rmi.md
View File

@ -1,4 +1,4 @@
# rmi # docker rmi
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Remove one or more images Remove one or more images
@ -17,91 +17,3 @@ Remove one or more images
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
Removes (and un-tags) one or more images from the host node. If an image has
multiple tags, using this command with the tag as a parameter only removes the
tag. If the tag is the only one for the image, both the image and the tag are
removed.
This does not remove images from a registry. You cannot remove an image of a
running container unless you use the `-f` option. To see all images on a host
use the [`docker image ls`](images.md) command.
## Examples
You can remove an image using its short or long ID, its tag, or its digest. If
an image has one or more tags referencing it, you must remove all of them before
the image is removed. Digest references are removed automatically when an image
is removed by tag.
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
$ docker rmi fd484f19954f
Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force
2013/12/11 05:47:16 Error: failed to remove one or more images
$ docker rmi test1:latest
Untagged: test1:latest
$ docker rmi test2:latest
Untagged: test2:latest
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
$ docker rmi test:latest
Untagged: test:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```
If you use the `-f` flag and specify the image's short or long ID, then this
command untags and removes all images that match the specified ID.
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB)
$ docker rmi -f fd484f19954f
Untagged: test1:latest
Untagged: test:latest
Untagged: test2:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```
An image pulled by digest has no tag associated with it:
```console
$ docker images --digests
REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB
```
To remove an image using its digest:
```console
$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
```

1560
docs/reference/commandline/run.md
View File

File diff suppressed because it is too large Load Diff

45
docs/reference/commandline/save.md
View File

@ -1,4 +1,4 @@
# save # docker save
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Save one or more images to a tar archive (streamed to STDOUT by default) Save one or more images to a tar archive (streamed to STDOUT by default)
@ -16,46 +16,3 @@ Save one or more images to a tar archive (streamed to STDOUT by default)
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
Produces a tarred repository to the standard output stream.
Contains all parent layers, and all tags + versions, or specified `repo:tag`, for
each argument provided.
## Examples
### Create a backup that can then be used with `docker load`.
```console
$ docker save busybox > busybox.tar
$ ls -sh busybox.tar
2.7M busybox.tar
$ docker save --output busybox.tar busybox
$ ls -sh busybox.tar
2.7M busybox.tar
$ docker save -o fedora-all.tar fedora
$ docker save -o fedora-latest.tar fedora:latest
```
### Save an image to a tar.gz file using gzip
You can use gzip to save the image file and make the backup smaller.
```console
$ docker save myimage:latest | gzip > myimage_latest.tar.gz
```
### Cherry-pick particular tags
You can even cherry-pick particular tags of an image repository.
```console
$ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy
```

7
docs/reference/commandline/start.md
View File

@ -1,4 +1,4 @@
# start # docker start
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Start one or more stopped containers Start one or more stopped containers
@ -20,8 +20,3 @@ Start one or more stopped containers
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Examples
```console
$ docker start my_container
```

182
docs/reference/commandline/stats.md
View File

@ -1,4 +1,4 @@
# stats # docker stats
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Display a live stream of container(s) resource usage statistics Display a live stream of container(s) resource usage statistics
@ -9,181 +9,13 @@ Display a live stream of container(s) resource usage statistics
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:--------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-a`, `--all` | | | Show all containers (default shows just running) | | `-a`, `--all` | | | Show all containers (default shows just running) |
| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `--no-stream` | | | Disable streaming stats and only pull the first result | | `--no-stream` | | | Disable streaming stats and only pull the first result |
| `--no-trunc` | | | Do not truncate output | | `--no-trunc` | | | Do not truncate output |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker stats` command returns a live data stream for running containers. To
limit data to one or more specific containers, specify a list of container names
or ids separated by a space. You can specify a stopped container but stopped
containers do not return any data.
If you need more detailed information about a container's resource usage, use
the `/containers/(id)/stats` API endpoint.
> **Note**
>
> On Linux, the Docker CLI reports memory usage by subtracting cache usage from
> the total memory usage. The API does not perform such a calculation but rather
> provides the total memory usage and the amount from the cache so that clients
> can use the data as needed. The cache usage is defined as the value of
> `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts.
>
> On Docker 19.03 and older, the cache usage was defined as the value of `cache`
> field. On cgroup v2 hosts, the cache usage is defined as the value of
> `inactive_file` field.
> **Note**
>
> The `PIDS` column contains the number of processes and kernel threads created
> by that container. Threads is the term used by Linux kernel. Other equivalent
> terms are "lightweight process" or "kernel task", etc. A large number in the
> `PIDS` column combined with a small number of processes (as reported by `ps`
> or `top`) may indicate that something in the container is creating many threads.
## Examples
Running `docker stats` on all running containers against a Linux daemon.
```console
$ docker stats
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9
67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2
e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1
4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2
```
If you don't [specify a format string using `--format`](#format), the
following columns are shown.
| Column name | Description |
|---------------------------|-----------------------------------------------------------------------------------------------|
| `CONTAINER ID` and `Name` | the ID and name of the container |
| `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using |
| `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use |
| `NET I/O` | The amount of data the container has received and sent over its network interface |
| `BLOCK I/O` | The amount of data the container has written to and read from block devices on the host |
| `PIDs` | the number of processes or threads the container has created |
Running `docker stats` on multiple containers by name and id against a Linux daemon.
```console
$ docker stats awesome_brattain 67b2525d8ad1
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9
67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2
```
Running `docker stats` on container with name `nginx` and getting output in `json` format.
```console
$ docker stats nginx --no-stream --format "{{ json . }}"
{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"}
```
Running `docker stats` with customized format on all (running and stopped) containers.
```console
$ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 humble_visvesvaraya big_heisenberg
CONTAINER CPU % MEM USAGE / LIMIT
fervent_panini 0.00% 56KiB / 15.57GiB
5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB
humble_visvesvaraya 0.00% 0B / 0B
big_heisenberg 0.00% 0B / 0B
```
`humble_visvesvaraya` and `big_heisenberg` are stopped containers in the above example.
Running `docker stats` on all running containers against a Windows daemon.
```powershell
PS E:\> docker stats
CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O
09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB
9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB
3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB
```
Running `docker stats` on multiple containers by name and id against a Windows daemon.
```powershell
PS E:\> docker ps -a
CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES
3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky
9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson
09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley
PS E:\> docker stats 3f214c61ad1d mad_wilson
CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O
3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB
9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) pretty prints container output
using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|--------------|----------------------------------------------|
| `.Container` | Container name or ID (user input) |
| `.Name` | Container name |
| `.ID` | Container ID |
| `.CPUPerc` | CPU percentage |
| `.MemUsage` | Memory usage |
| `.NetIO` | Network IO |
| `.BlockIO` | Block IO |
| `.MemPerc` | Memory percentage (Not available on Windows) |
| `.PIDs` | Number of PIDs (Not available on Windows) |
When using the `--format` option, the `stats` command either
outputs the data exactly as the template declares or, when using the
`table` directive, includes column headers as well.
The following example uses a template without headers and outputs the
`Container` and `CPUPerc` entries separated by a colon (`:`) for all images:
```console
$ docker stats --format "{{.Container}}: {{.CPUPerc}}"
09d3bb5b1604: 6.61%
9db7aa4d986d: 9.19%
3f214c61ad1d: 0.00%
```
To list all containers statistics with their name, CPU percentage and memory
usage in a table format you can use:
```console
$ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
CONTAINER CPU % PRIV WORKING SET
1285939c1fd3 0.07% 796 KiB / 64 MiB
9c76f7834ae2 0.07% 2.746 MiB / 64 MiB
d1ea048f04e4 0.03% 4.583 MiB / 64 MiB
```
The default format is as follows:
On Linux:
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}"
On Windows:
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"

14
docs/reference/commandline/stop.md
View File

@ -1,4 +1,4 @@
# stop # docker stop
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Stop one or more running containers Stop one or more running containers
@ -17,15 +17,3 @@ Stop one or more running containers
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The main process inside the container will receive `SIGTERM`, and after a grace
period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL`
instruction in the container's Dockerfile, or the `--stop-signal` option to
`docker run`.
## Examples
```console
$ docker stop my_container
```

166
docs/reference/commandline/system_events.md
View File

@ -1,4 +1,4 @@
# system events # events
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Get real time events from the server Get real time events from the server
@ -13,7 +13,7 @@ Get real time events from the server
|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | | [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
| [`--format`](#format) | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | [`--format`](#format) | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| `--since` | `string` | | Show all events created since timestamp | | [`--since`](#since) | `string` | | Show all events created since timestamp |
| `--until` | `string` | | Stream events until this timestamp | | `--until` | `string` | | Stream events until this timestamp |
@ -21,8 +21,13 @@ Get real time events from the server
## Description ## Description
Use `docker system events` to get real-time events from the server. These Use `docker events` to get real-time events from the server. These events differ
events differ per Docker object type. per Docker object type. Different event types have different scopes. Local
scoped events are only seen on the node they take place on, and Swarm scoped
events are seen on all managers.
Only the last 1000 log events are returned. You can use filters to further limit
the number of events returned.
### Object types ### Object types
@ -72,9 +77,9 @@ Docker images report the following events:
Docker plugins report the following events: Docker plugins report the following events:
- `install`
- `enable` - `enable`
- `disable` - `disable`
- `install`
- `remove` - `remove`
#### Volumes #### Volumes
@ -82,9 +87,9 @@ Docker plugins report the following events:
Docker volumes report the following events: Docker volumes report the following events:
- `create` - `create`
- `destroy`
- `mount` - `mount`
- `unmount` - `unmount`
- `destroy`
#### Networks #### Networks
@ -92,8 +97,9 @@ Docker networks report the following events:
- `create` - `create`
- `connect` - `connect`
- `disconnect`
- `destroy` - `destroy`
- `disconnect`
- `remove`
#### Daemons #### Daemons
@ -101,9 +107,41 @@ Docker daemons report the following events:
- `reload` - `reload`
#### Services
Docker services report the following events:
- `create`
- `remove`
- `update`
#### Nodes
Docker nodes report the following events:
- `create`
- `remove`
- `update`
#### Secrets
Docker secrets report the following events:
- `create`
- `remove`
- `update`
#### Configs
Docker configs report the following events:
- `create`
- `remove`
- `update`
### Limiting, filtering, and formatting the output ### Limiting, filtering, and formatting the output
#### Limit events by time #### <a name="since"></a> Limit events by time (--since, --until)
The `--since` and `--until` parameters can be Unix timestamps, date formatted The `--since` and `--until` parameters can be Unix timestamps, date formatted
timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed
@ -118,31 +156,48 @@ 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 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
fraction of a second no more than nine digits long. fraction of a second no more than nine digits long.
Only the last 1000 log events are returned. You can use filters to further limit
the number of events returned.
#### <a name="filter"></a> Filtering (--filter) #### <a name="filter"></a> Filtering (--filter)
The filtering flag (`-f` or `--filter`) format is of "key=value". If you would The filtering flag (`-f` or `--filter`) format is of "key=value". If you would
like to use multiple filters, pass multiple flags (e.g., like to use multiple filters, pass multiple flags (e.g.,
`--filter "foo=bar" --filter "bif=baz"`) `--filter "foo=bar" --filter "bif=baz"`)
Using the same filter multiple times will be handled as a logical `OR`; for example, Using the same filter multiple times is interpreted as a logical `OR`; for example,
`--filter container=588a23dac085 --filter container=a8f7720b8c22` displays `--filter container=588a23dac085 --filter container=a8f7720b8c22` displays
events for container `588a23dac085` or container `a8f7720b8c22`. events for container `588a23dac085` or container `a8f7720b8c22`.
Using multiple filters will be handled as a logical `AND`; for example, Using multiple filters is interpreted as a logical `AND`; for example,
`--filter container=588a23dac085 --filter event=start` displays events for `--filter container=588a23dac085 --filter event=start` displays events for
container `588a23dac085` and where the event type is `start`. container `588a23dac085` and where the event type is `start`.
The currently supported filters are: The currently supported filters are:
- config (`config=<name or id>`)
- container (`container=<name or id>`) - container (`container=<name or id>`)
- daemon (`daemon=<name or id>`) - daemon (`daemon=<name or id>`)
- event (`event=<event action>`) - event (`event=<event action>`)
- image (`image=<tag or id>`) - image (`image=<repository or tag>`)
- label (`label=<key>` or `label=<key>=<value>`) - label (`label=<key>` or `label=<key>=<value>`)
- network (`network=<name or id>`) - network (`network=<name or id>`)
- node (`node=<id>`)
- plugin (`plugin=<name or id>`) - plugin (`plugin=<name or id>`)
- type (`type=<container or image or volume or network or daemon or plugin>`) - scope (`scope=<local or swarm>`)
- volume (`volume=<name or id>`) - secret (`secret=<name or id>`)
- service (`service=<name or id>`)
- type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
- volume (`volume=<name>`)
#### <a name="format"></a> Format the output (--format)
If you specify a format (`--format`), the given template is executed
instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
package describes all the details of the format.
If a format is set to `{{json .}}`, events are streamed in the JSON Lines format.
For information about JSON Lines, see <https://jsonlines.org/>.
## Examples ## Examples
@ -153,7 +208,7 @@ You'll need two shells for this example.
**Shell 1: Listening for events:** **Shell 1: Listening for events:**
```console ```console
$ docker system events $ docker events
``` ```
**Shell 2: Start and Stop containers:** **Shell 2: Start and Stop containers:**
@ -176,7 +231,7 @@ $ docker stop test
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
``` ```
To exit the `docker system events` command, use `CTRL+C`. To exit the `docker events` command, use `CTRL+C`.
### Filter events by time ### Filter events by time
@ -184,8 +239,7 @@ You can filter the output by an absolute timestamp or relative time on the host
machine, using the following different time formats: machine, using the following different time formats:
```console ```console
$ docker system events --since 1483283804 $ docker events --since 1483283804
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
@ -195,8 +249,7 @@ $ docker system events --since 1483283804
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker system events --since '2017-01-05' $ docker events --since '2017-01-05'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
@ -206,8 +259,7 @@ $ docker system events --since '2017-01-05'
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker system events --since '2013-09-03T15:49:29' $ docker events --since '2013-09-03T15:49:29'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
@ -217,8 +269,7 @@ $ docker system events --since '2013-09-03T15:49:29'
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker system events --since '10m' $ docker events --since '10m'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
@ -227,6 +278,12 @@ $ docker system events --since '10m'
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36:05'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
``` ```
### Filter events by criteria ### Filter events by criteria
@ -235,12 +292,12 @@ The following commands show several different ways to filter the `docker event`
output. output.
```console ```console
$ docker system events --filter 'event=stop' $ docker events --filter 'event=stop'
2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) 2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain)
$ docker system events --filter 'image=alpine' $ docker events --filter 'image=alpine'
2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) 2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner)
2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) 2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
@ -249,14 +306,14 @@ $ docker system events --filter 'image=alpine'
2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) 2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner)
2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) 2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner)
$ docker system events --filter 'container=test' $ docker events --filter 'container=test'
2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) 2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) 2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
$ docker system events --filter 'container=test' --filter 'container=d9cdb1525ea8' $ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8'
2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) 2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
@ -264,55 +321,74 @@ $ docker system events --filter 'container=test' --filter 'container=d9cdb1525ea
2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) 2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test)
2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) 2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test)
$ docker system events --filter 'container=test' --filter 'event=stop' $ docker events --filter 'container=test' --filter 'event=stop'
2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test)
$ docker system events --filter 'type=volume' $ docker events --filter 'type=volume'
2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate)
2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local)
2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
$ docker system events --filter 'type=network' $ docker events --filter 'type=network'
2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) 2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge)
2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) 2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge)
$ docker system events --filter 'container=container_1' --filter 'container=container_2' $ docker events --filter 'container=container_1' --filter 'container=container_2'
2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04 ) 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04)
2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04 ) 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04)
2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8)
2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8)
$ docker system events --filter 'type=volume' $ docker events --filter 'type=volume'
2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate) 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate)
2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local) 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local)
2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)
$ docker system events --filter 'type=network' $ docker events --filter 'type=network'
2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) 2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge)
2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) 2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge)
$ docker system events --filter 'type=plugin' $ docker events --filter 'type=plugin'
2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
$ docker events -f type=service
2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
$ docker events -f type=node
2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown)
$ docker events -f type=secret
2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
$ docker events -f type=config
2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
$ docker events --filter 'scope=swarm'
2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson)
2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret)
``` ```
### <a name="format"></a> Format the output (--format) ### Format the output
If you specify a format (`--format`), the given template is executed
instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
package describes all the details of the format.
```console ```console
$ docker system events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' $ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}'
Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
@ -324,11 +400,11 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299
#### Format as JSON #### Format as JSON
If a format is set to `{{json .}}`, events are streamed in the JSON Lines format. To list events in JSON format, use the `json` directive, which is the same
For information about JSON Lines, see <https://jsonlines.org/>. `--format '{{ json . }}`.
```console ```console
$ docker system events --format '{{json .}}' $ docker events --format json
{"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..

167
docs/reference/commandline/system_info.md
View File

@ -1,4 +1,4 @@
# system info # info
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Display system-wide information Display system-wide information
@ -9,10 +9,169 @@ Display system-wide information
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-f`, `--format` | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | | [`-f`](#format), [`--format`](#format) | `string` | | Format output using a custom template:<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
This command displays system wide information regarding the Docker installation.
Information displayed includes the kernel version, number of containers and images.
The number of images shown is the number of unique images. The same image tagged
under different names is counted only once.
If a format is specified, the given template will be executed instead of the
default format. Go's [text/template](https://pkg.go.dev/text/template) package
describes all the details of the format.
Depending on the storage driver in use, additional information can be shown, such
as pool name, data file, metadata file, data space used, total data space, metadata
space used, and total metadata space.
The data file is where the images are stored and the metadata file is where the
meta data regarding those images are stored. When run for the first time Docker
allocates a certain amount of data space and meta data space from the space
available on the volume where `/var/lib/docker` is mounted.
## Examples
### Show output
The example below shows the output for a daemon running on Ubuntu Linux,
using the `overlay2` storage driver. As can be seen in the output, additional
information about the `overlay2` storage driver is shown:
```console
$ docker info
Client: Docker Engine - Community
Version: 24.0.0
Context: default
Debug Mode: false
Plugins:
buildx: Docker Buildx (Docker Inc.)
Version: v0.10.4
Path: /usr/libexec/docker/cli-plugins/docker-buildx
compose: Docker Compose (Docker Inc.)
Version: v2.17.2
Path: /usr/libexec/docker/cli-plugins/docker-compose
Server:
Containers: 14
Running: 3
Paused: 1
Stopped: 10
Images: 52
Server Version: 23.0.3
Storage Driver: overlay2
Backing Filesystem: extfs
Supports d_type: true
Using metacopy: false
Native Overlay Diff: true
userxattr: false
Logging Driver: json-file
Cgroup Driver: systemd
Cgroup Version: 2
Plugins:
Volume: local
Network: bridge host ipvlan macvlan null overlay
Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
CDI spec directories:
/etc/cdi
/var/run/cdi
Swarm: inactive
Runtimes: io.containerd.runc.v2 runc
Default Runtime: runc
Init Binary: docker-init
containerd version: 2806fc1057397dbaeefbea0e4e17bddfbd388f38
runc version: v1.1.5-0-gf19387a
init version: de40ad0
Security Options:
apparmor
seccomp
Profile: builtin
cgroupns
Kernel Version: 5.15.0-25-generic
Operating System: Ubuntu 22.04 LTS
OSType: linux
Architecture: x86_64
CPUs: 1
Total Memory: 991.7 MiB
Name: ip-172-30-0-91.ec2.internal
ID: 4cee4408-10d2-4e17-891c-a41736ac4536
Docker Root Dir: /var/lib/docker
Debug Mode: false
Username: gordontheturtle
Experimental: false
Insecure Registries:
myinsecurehost:5000
127.0.0.0/8
Live Restore Enabled: false
```
### <a name="format"></a> Format the output (--format)
You can also specify the output format:
```console
$ docker info --format '{{json .}}'
{"ID":"4cee4408-10d2-4e17-891c-a41736ac4536","Containers":14, ...}
```
### Run `docker info` on Windows
Here is a sample output for a daemon running on Windows Server:
```console
C:\> docker info
Client: Docker Engine - Community
Version: 24.0.0
Context: default
Debug Mode: false
Plugins:
buildx: Docker Buildx (Docker Inc.)
Version: v0.10.4
Path: C:\Program Files\Docker\cli-plugins\docker-buildx.exe
compose: Docker Compose (Docker Inc.)
Version: v2.17.2
Path: C:\Program Files\Docker\cli-plugins\docker-compose.exe
Server:
Containers: 1
Running: 0
Paused: 0
Stopped: 1
Images: 17
Server Version: 23.0.3
Storage Driver: windowsfilter
Logging Driver: json-file
Plugins:
Volume: local
Network: ics internal l2bridge l2tunnel nat null overlay private transparent
Log: awslogs etwlogs fluentd gcplogs gelf json-file local splunk syslog
Swarm: inactive
Default Isolation: process
Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500)
Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707)
OSType: windows
Architecture: x86_64
CPUs: 8
Total Memory: 3.999 GiB
Name: WIN-V0V70C0LU5P
ID: 2880d38d-464e-4d01-91bd-c76f33ba3981
Docker Root Dir: C:\ProgramData\docker
Debug Mode: false
Experimental: true
Insecure Registries:
myregistry:5000
127.0.0.0/8
Registry Mirrors:
http://192.168.1.2/
http://registry-mirror.example.com:5000/
Live Restore Enabled: false
```

77
docs/reference/commandline/tag.md
View File

@ -1,4 +1,4 @@
# tag # docker tag
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
@ -10,78 +10,3 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
A full image name has the following format and components:
`[HOST[:PORT_NUMBER]/]PATH`
- `HOST`: The optional registry hostname specifies where the image is located.
The hostname must comply with standard DNS rules, but may not contain
underscores. If you don't specify a hostname, the command uses Docker's public
registry at `registry-1.docker.io` by default. Note that `docker.io` is the
canonical reference for Docker's public registry.
- `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a
registry port number in the format `:8080`.
- `PATH`: The path consists of slash-separated components. Each
component may contain lowercase letters, digits and separators. A separator is
defined as a period, one or two underscores, or one or more hyphens. A component
may not start or end with a separator. While the
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)
supports more than two slash-separated components, most registries only support
two slash-separated components. For Docker's public registry, the path format is
as follows:
- `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a
user's or an organization's namespace. The second, mandatory component is the
repository name. When the namespace is not present, Docker uses `library`
as the default namespace.
After the image name, the optional `TAG` is a custom, human-readable manifest
identifier that's typically a specific version or variant of an image. The tag
must be valid ASCII and can contain lowercase and uppercase letters, digits,
underscores, periods, and hyphens. It can't start with a period or hyphen and
must be no longer than 128 characters. If you don't specify a tag, the command uses `latest` by default.
You can group your images together using names and tags, and then
[push](https://docs.docker.com/engine/reference/commandline/push) them to a
registry.
## Examples
### Tag an image referenced by ID
To tag a local image with ID `0e5574283393` as `fedora/httpd` with the tag
`version1.0`:
```console
$ docker tag 0e5574283393 fedora/httpd:version1.0
```
### Tag an image referenced by Name
To tag a local image `httpd` as `fedora/httpd` with the tag `version1.0`:
```console
$ docker tag httpd fedora/httpd:version1.0
```
Note that since the tag name isn't specified, the alias is created for an
existing local version `httpd:latest`.
### Tag an image referenced by Name and Tag
To tag a local image with the name `httpd` and the tag `test` as `fedora/httpd`
with the tag `version1.0.test`:
```console
$ docker tag httpd:test fedora/httpd:version1.0.test
```
### Tag an image for a private registry
To push an image to a private registry and not the public Docker registry you
must include the registry hostname and port (if needed).
```console
$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0
```

3
docs/reference/commandline/top.md
View File

@ -1,4 +1,4 @@
# top # docker top
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Display the running processes of a container Display the running processes of a container
@ -9,3 +9,4 @@ Display the running processes of a container
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->

21
docs/reference/commandline/unpause.md
View File

@ -1,4 +1,4 @@
# unpause # docker unpause
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Unpause all processes within one or more containers Unpause all processes within one or more containers
@ -10,22 +10,3 @@ Unpause all processes within one or more containers
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker unpause` command un-suspends all processes in the specified containers.
On Linux, it does this using the freezer cgroup.
See the
[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
for further details.
## Examples
```console
$ docker unpause my_container
my_container
```
## Related commands
* [pause](pause.md)

127
docs/reference/commandline/update.md
View File

@ -1,4 +1,4 @@
## update # docker update
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Update configuration of one or more containers Update configuration of one or more containers
@ -9,116 +9,23 @@ Update configuration of one or more containers
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:---------------------------------------------------|:----------|:--------|:-----------------------------------------------------------------------------| |:-----------------------|:----------|:--------|:-----------------------------------------------------------------------------|
| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | | `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) |
| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | | `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period |
| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | | `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota |
| `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds | | `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds |
| `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds | | `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds |
| [`-c`](#cpu-shares), [`--cpu-shares`](#cpu-shares) | `int64` | `0` | CPU shares (relative weight) | | `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
| `--cpus` | `decimal` | | Number of CPUs | | `--cpus` | `decimal` | | Number of CPUs |
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | | `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | | `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | | `-m`, `--memory` | `bytes` | `0` | Memory limit |
| `--memory-reservation` | `bytes` | `0` | Memory soft limit | | `--memory-reservation` | `bytes` | `0` | Memory soft limit |
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | | `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | | `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) |
| [`--restart`](#restart) | `string` | | Restart policy to apply when a container exits | | `--restart` | `string` | | Restart policy to apply when a container exits |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description
The `docker update` command dynamically updates container configuration.
You can use this command to prevent containers from consuming too many
resources from their Docker host. With a single command, you can place
limits on a single container or on many. To specify more than one container,
provide space-separated list of container names or IDs.
With the exception of the `--kernel-memory` option, you can specify these
options on a running or a stopped container. On kernel version older than
4.6, you can only update `--kernel-memory` on a stopped container or on
a running container with kernel memory initialized.
> **Warning**
>
> The `docker update` and `docker container update` commands are not supported
> for Windows containers.
{ .warning }
## Examples
The following sections illustrate ways to use this command.
### <a name="cpu-shares"></a> Update a container's cpu-shares (--cpu-shares)
To limit a container's cpu-shares to 512, first identify the container
name or ID. You can use `docker ps` to find these values. You can also
use the ID returned from the `docker run` command. Then, do the following:
```console
$ docker update --cpu-shares 512 abebf7571666
```
### <a name="memory"></a> Update a container with cpu-shares and memory (-m, --memory)
To update multiple resource configurations for multiple containers:
```console
$ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse
```
### <a name="kernel-memory"></a> Update a container's kernel memory constraints (--kernel-memory)
You can update a container's kernel memory limit using the `--kernel-memory`
option. On kernel version older than 4.6, this option can be updated on a
running container only if the container was started with `--kernel-memory`.
If the container was started without `--kernel-memory` you need to stop
the container before updating kernel memory.
> **Note**
>
> The `--kernel-memory` option has been deprecated since Docker 20.10.
For example, if you started a container with this command:
```console
$ docker run -dit --name test --kernel-memory 50M ubuntu bash
```
You can update kernel memory while the container is running:
```console
$ docker update --kernel-memory 80M test
```
If you started a container without kernel memory initialized:
```console
$ docker run -dit --name test2 --memory 300M ubuntu bash
```
Update kernel memory of running container `test2` will fail. You need to stop
the container before updating the `--kernel-memory` setting. The next time you
start it, the container uses the new value.
Kernel version newer than (include) 4.6 does not have this limitation, you
can use `--kernel-memory` the same way as other options.
### <a name="restart"></a> Update a container's restart policy (--restart)
You can change a container's restart policy on a running container. The new
restart policy takes effect instantly after you run `docker update` on a
container.
To update restart policy for one or more containers:
```console
$ docker update --restart=on-failure:3 abebf7571666 hopeful_morse
```
Note that if the container is started with `--rm` flag, you cannot update the restart
policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the
container.

36
docs/reference/commandline/wait.md
View File

@ -1,4 +1,4 @@
# wait # docker wait
<!---MARKER_GEN_START--> <!---MARKER_GEN_START-->
Block until one or more containers stop, then print their exit codes Block until one or more containers stop, then print their exit codes
@ -10,37 +10,3 @@ Block until one or more containers stop, then print their exit codes
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
> **Note**
>
> `docker wait` returns `0` when run against a container which had already
> exited before the `docker wait` command was run.
## Examples
Start a container in the background.
```console
$ docker run -dit --name=my_container ubuntu bash
```
Run `docker wait`, which should block until the container exits.
```console
$ docker wait my_container
```
In another terminal, stop the first container. The `docker wait` command above
returns the exit code.
```console
$ docker stop my_container
```
This is the same `docker wait` command from above, but it now exits, returning
`0`.
```console
$ docker wait my_container
0
```

12
docs/reference/run.md
View File

@ -114,13 +114,13 @@ $ docker attach 0246aa4d1448
For more information about `docker run` flags related to foreground and For more information about `docker run` flags related to foreground and
background modes, see: background modes, see:
- [`docker run --detach`](commandline/run.md#detach): run container in background - [`docker run --detach`](commandline/container_run.md#detach): run container in background
- [`docker run --attach`](commandline/run.md#attach): attach to `stdin`, `stdout`, and `stderr` - [`docker run --attach`](commandline/container_run.md#attach): attach to `stdin`, `stdout`, and `stderr`
- [`docker run --tty`](commandline/run.md#tty): allocate a pseudo-tty - [`docker run --tty`](commandline/container_run.md#tty): allocate a pseudo-tty
- [`docker run --interactive`](commandline/run.md#interactive): keep `stdin` open even if not attached - [`docker run --interactive`](commandline/container_run.md#interactive): keep `stdin` open even if not attached
For more information about re-attaching to a background container, see For more information about re-attaching to a background container, see
[`docker attach`](commandline/attach.md). [`docker attach`](commandline/container_attach.md).
## Container identification ## Container identification
@ -135,7 +135,7 @@ You can identify a container in three ways:
The UUID identifier is a random ID assigned to the container by the daemon. The UUID identifier is a random ID assigned to the container by the daemon.
The daemon generates a random string name for containers automatically. You can The daemon generates a random string name for containers automatically. You can
also defined a custom name using [the `--name` flag](./commandline/run.md#name). also defined a custom name using [the `--name` flag](./commandline/container_run.md#name).
Defining a `name` can be a handy way to add meaning to a container. If you Defining a `name` can be a handy way to add meaning to a container. If you
specify a `name`, you can use it when referring to the container in a specify a `name`, you can use it when referring to the container in a
user-defined network. This works for both background and foreground Docker user-defined network. This works for both background and foreground Docker