0a0dd116 |
% DOCKER(1) Docker User Manuals |
b07f1938 |
% Docker Community
% JUNE 2014 |
0a0dd116 |
# NAME |
e54b1e08 |
docker-cp - Copy files/folders between a container and the local filesystem. |
0a0dd116 |
# SYNOPSIS |
b07f1938 |
**docker cp** |
a2b529ea |
[**--help**] |
92600bde |
CONTAINER:SRC_PATH DEST_PATH|- |
d7904696 |
**docker cp**
[**--help**] |
92600bde |
SRC_PATH|- CONTAINER:DEST_PATH |
0a0dd116 |
# DESCRIPTION |
9a78ed8f |
|
92600bde |
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. |
877e6d76 |
The `SRC_PATH` or `DEST_PATH` can be a file or directory. |
92600bde |
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 |
e54b1e08 |
copied recursively with permissions preserved if possible. Ownership is set to |
92600bde |
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. If you specify the `-L` option, `docker cp` follows any symbolic link |
889d0617 |
in the `SRC_PATH`. `docker cp` does *not* create parent directories for
`DEST_PATH` if they do not exist. |
e54b1e08 |
Assuming a path separator of `/`, a first argument of `SRC_PATH` and second |
92600bde |
argument of `DEST_PATH`, the behavior is as follows: |
e54b1e08 |
- `SRC_PATH` specifies a file |
92600bde |
- `DEST_PATH` does not exist
- the file is saved to a file created at `DEST_PATH`
- `DEST_PATH` does not exist and ends with `/` |
e54b1e08 |
- Error condition: the destination directory must exist. |
92600bde |
- `DEST_PATH` exists and is a file
- the destination is overwritten with the source file's contents
- `DEST_PATH` exists and is a directory |
e54b1e08 |
- the file is copied into this directory using the basename from
`SRC_PATH`
- `SRC_PATH` specifies a directory |
92600bde |
- `DEST_PATH` does not exist
- `DEST_PATH` is created as a directory and the *contents* of the source |
e54b1e08 |
directory are copied into this directory |
92600bde |
- `DEST_PATH` exists and is a file |
e54b1e08 |
- Error condition: cannot copy a directory to a file |
92600bde |
- `DEST_PATH` exists and is a directory |
e54b1e08 |
- `SRC_PATH` does not end with `/.`
- the source directory is copied into this directory |
386b7bc7 |
- `SRC_PATH` does end with `/.` |
e54b1e08 |
- the *content* of the source directory is copied into this
directory
|
92600bde |
The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above |
e54b1e08 |
rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not |
92600bde |
the target, is copied by default. To copy the link target and not the link,
specify the `-L` option. |
e54b1e08 |
|
92600bde |
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: |
e54b1e08 |
`/path/to/file:name.txt` or `./file:name.txt`
It is not possible to copy certain system files such as resources under
`/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
|
92600bde |
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 |
877e6d76 |
the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`. |
e54b1e08 |
# OPTIONS |
92600bde |
**-L**, **--follow-link**=*true*|*false*
Follow symbol link in SRC_PATH
|
e54b1e08 |
**--help**
Print usage statement
# EXAMPLES
Suppose a container has finished producing some output as a file it saves
to somewhere in its filesystem. This could be the output of a build job or
some other computation. You can copy these outputs from the container to a
location on your local host. |
9a78ed8f |
|
e54b1e08 |
If you want to copy the `/tmp/foo` directory from a container to the
existing `/tmp` directory on your host. If you run `docker cp` in your `~`
(home) directory on the local host: |
9a78ed8f |
|
92600bde |
$ docker cp compassionate_darwin:tmp/foo /tmp |
9a78ed8f |
Docker creates a `/tmp/foo` directory on your host. Alternatively, you can omit |
e54b1e08 |
the leading slash in the command. If you execute this command from your home
directory: |
9a78ed8f |
|
92600bde |
$ docker cp compassionate_darwin:tmp/foo tmp |
9a78ed8f |
|
e54b1e08 |
If `~/tmp` does not exist, Docker will create it and copy the contents of
`/tmp/foo` from the container into this new directory. If `~/tmp` already
exists as a directory, then Docker will copy the contents of `/tmp/foo` from
the container into a directory at `~/tmp/foo`. |
9a78ed8f |
|
e54b1e08 |
When copying a single file to an existing `LOCALPATH`, the `docker cp` command
will either overwrite the contents of `LOCALPATH` if it is a file or place it
into `LOCALPATH` if it is a directory, overwriting an existing file of the same
name if one exists. For example, this command: |
9a78ed8f |
|
92600bde |
$ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /test |
9a78ed8f |
|
e54b1e08 |
If `/test` does not exist on the local machine, it will be created as a file
with the contents of `/tmp/foo/myfile.txt` from the container. If `/test` |
725b7c9d |
exists as a file, it will be overwritten. Lastly, if `/test` exists as a |
e54b1e08 |
directory, the file will be copied to `/test/myfile.txt`. |
9a78ed8f |
|
e54b1e08 |
Next, suppose you want to copy a file or folder into a container. For example,
this could be a configuration file or some other input to a long running
computation that you would like to place into a created container before it
starts. This is useful because it does not require the configuration file or
other input to exist in the container image. |
9a78ed8f |
|
e54b1e08 |
If you have a file, `config.yml`, in the current directory on your local host
and wish to copy it to an existing directory at `/etc/my-app.d` in a container,
this command can be used: |
9a78ed8f |
|
92600bde |
$ docker cp config.yml myappcontainer:/etc/my-app.d |
0a0dd116 |
|
e54b1e08 |
If you have several files in a local directory `/config` which you need to copy
to a directory `/etc/my-app.d` in a container: |
b07f1938 |
|
92600bde |
$ docker cp /config/. myappcontainer:/etc/my-app.d |
0a0dd116 |
|
e54b1e08 |
The above command will copy the contents of the local `/config` directory into
the directory `/etc/my-app.d` in the container. |
0a0dd116 |
|
92600bde |
Finally, if you want to copy a symbolic link into a container, you typically
want to copy the linked target and not the link itself. To copy the target, use
the `-L` option, for example:
$ ln -s /tmp/somefile /tmp/somefile.ln
$ docker cp -L /tmp/somefile.ln myappcontainer:/tmp/
This command copies content of the local `/tmp/somefile` into the file
`/tmp/somefile.ln` in the container. Without `-L` option, the `/tmp/somefile.ln`
preserves its symbolic link but not its content.
|
0a0dd116 |
# HISTORY
April 2014, Originally compiled by William Henry (whenry at redhat dot com) |
fa29b1f0 |
based on docker.com source material and internal work. |
b07f1938 |
June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> |
e54b1e08 |
May 2015, updated by Josh Hawn <josh.hawn@docker.com> |