1# cp
2
3<!---MARKER_GEN_START-->
4Copy files/folders between a container and the local filesystem
5
6Use '-' as the source to read a tar archive from stdin
7and extract it to a directory destination in a container.
8Use '-' as the destination to stream a tar archive of a
9container source to stdout.
10
11### Aliases
12
13`docker container cp`, `docker cp`
14
15### Options
16
17| Name | Type | Default | Description |
18|:----------------------|:-----|:--------|:-------------------------------------------------------------------------------------------------------------|
19| `-a`, `--archive` | | | Archive mode (copy all uid/gid information) |
20| `-L`, `--follow-link` | | | Always follow symbol link in SRC_PATH |
21| `-q`, `--quiet` | | | Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached |
22
23
24<!---MARKER_GEN_END-->
25
26## Description
27
28The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`.
29You can copy from the container's file system to the local machine or the
30reverse, from the local filesystem to the container. If `-` is specified for
31either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from
32`STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container.
33The `SRC_PATH` or `DEST_PATH` can be a file or directory.
34
35The `docker cp` command assumes container paths are relative to the container's
36`/` (root) directory. This means supplying the initial forward slash is optional;
37The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and
38`compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can
39be an absolute or relative value. The command interprets a local machine's
40relative paths as relative to the current working directory where `docker cp` is
41run.
42
43The `cp` command behaves like the Unix `cp -a` command in that directories are
44copied recursively with permissions preserved if possible. Ownership is set to
45the user and primary group at the destination. For example, files copied to a
46container are created with `UID:GID` of the root user. Files copied to the local
47machine are created with the `UID:GID` of the user which invoked the `docker cp`
48command. However, if you specify the `-a` option, `docker cp` sets the ownership
49to the user and primary group at the source.
50If you specify the `-L` option, `docker cp` follows any symbolic link
51in the `SRC_PATH`. `docker cp` doesn't create parent directories for
52`DEST_PATH` if they don't exist.
53
54Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
55argument of `DEST_PATH`, the behavior is as follows:
56
57- `SRC_PATH` specifies a file
58 - `DEST_PATH` does not exist
59 - the file is saved to a file created at `DEST_PATH`
60 - `DEST_PATH` does not exist and ends with `/`
61 - Error condition: the destination directory must exist.
62 - `DEST_PATH` exists and is a file
63 - the destination is overwritten with the source file's contents
64 - `DEST_PATH` exists and is a directory
65 - the file is copied into this directory using the basename from
66 `SRC_PATH`
67- `SRC_PATH` specifies a directory
68 - `DEST_PATH` does not exist
69 - `DEST_PATH` is created as a directory and the *contents* of the source
70 directory are copied into this directory
71 - `DEST_PATH` exists and is a file
72 - Error condition: cannot copy a directory to a file
73 - `DEST_PATH` exists and is a directory
74 - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_)
75 - the source directory is copied into this directory
76 - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_)
77 - the *content* of the source directory is copied into this
78 directory
79
80The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above
81rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
82the target, is copied by default. To copy the link target and not the link, specify
83the `-L` option.
84
85A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can
86also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local
87machine, for example `file:name.txt`. If you use a `:` in a local machine path,
88you must be explicit with a relative or absolute path, for example:
89
90 `/path/to/file:name.txt` or `./file:name.txt`
91
92## Examples
93
94Copy a local file into container
95
96```console
97$ docker cp ./some_file CONTAINER:/work
98```
99
100Copy files from container to local path
101
102```console
103$ docker cp CONTAINER:/var/logs/ /tmp/app_logs
104```
105
106Copy a file from container to stdout. Please note `cp` command produces a tar stream
107
108```console
109$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR"
110```
111
112### Corner cases
113
114It isn't possible to copy certain system files such as resources under
115`/proc`, `/sys`, `/dev`, [tmpfs](container_run.md#tmpfs), and mounts created by
116the user in the container. However, you can still copy such files by manually
117running `tar` in `docker exec`. Both of the following examples do the same thing
118in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):
119
120```console
121$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
122```
123
124```console
125$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH -
126```
127
128Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
129The command extracts the content of the tar to the `DEST_PATH` in container's
130filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as
131the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.
View as plain text