github.com/gunjan5/docker@v1.8.2/man/docker-cp.1.md (about)

     1  % DOCKER(1) Docker User Manuals
     2  % Docker Community
     3  % JUNE 2014
     4  # NAME
     5  docker-cp - Copy files/folders between a container and the local filesystem.
     6  
     7  # SYNOPSIS
     8  **docker cp**
     9  [**--help**]
    10  CONTAINER:PATH LOCALPATH|-
    11  LOCALPATH|- CONTAINER:PATH
    12  
    13  # DESCRIPTION
    14  
    15  In the first synopsis form, the `docker cp` utility copies the contents of
    16  `PATH` from the filesystem of `CONTAINER` to the `LOCALPATH` (or stream as
    17  a tar archive to `STDOUT` if `-` is specified).
    18  
    19  In the second synopsis form, the contents of `LOCALPATH` (or a tar archive
    20  streamed from `STDIN` if `-` is specified) are copied from the local machine to
    21  `PATH` in the filesystem of `CONTAINER`.
    22  
    23  You can copy to or from either a running or stopped container. The `PATH` can
    24  be a file or directory. The `docker cp` command assumes all `CONTAINER:PATH`
    25  values are relative to the `/` (root) directory of the container. This means
    26  supplying the initial forward slash is optional; The command sees
    27  `compassionate_darwin:/tmp/foo/myfile.txt` and
    28  `compassionate_darwin:tmp/foo/myfile.txt` as identical. If a `LOCALPATH` value
    29  is not absolute, is it considered relative to the current working directory.
    30  
    31  Behavior is similar to the common Unix utility `cp -a` in that directories are
    32  copied recursively with permissions preserved if possible. Ownership is set to
    33  the user and primary group on the receiving end of the transfer. For example,
    34  files copied to a container will be created with `UID:GID` of the root user.
    35  Files copied to the local machine will be created with the `UID:GID` of the
    36  user which invoked the `docker cp` command.
    37  
    38  Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
    39  argument of `DST_PATH`, the behavior is as follows:
    40  
    41  - `SRC_PATH` specifies a file
    42      - `DST_PATH` does not exist
    43          - the file is saved to a file created at `DST_PATH`
    44      - `DST_PATH` does not exist and ends with `/`
    45          - Error condition: the destination directory must exist.
    46      - `DST_PATH` exists and is a file
    47          - the destination is overwritten with the contents of the source file
    48      - `DST_PATH` exists and is a directory
    49          - the file is copied into this directory using the basename from
    50            `SRC_PATH`
    51  - `SRC_PATH` specifies a directory
    52      - `DST_PATH` does not exist
    53          - `DST_PATH` is created as a directory and the *contents* of the source
    54             directory are copied into this directory
    55      - `DST_PATH` exists and is a file
    56          - Error condition: cannot copy a directory to a file
    57      - `DST_PATH` exists and is a directory
    58          - `SRC_PATH` does not end with `/.`
    59              - the source directory is copied into this directory
    60          - `SRC_PAPTH` does end with `/.`
    61              - the *content* of the source directory is copied into this
    62                directory
    63  
    64  The command requires `SRC_PATH` and `DST_PATH` to exist according to the above
    65  rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
    66  the target, is copied.
    67  
    68  A colon (`:`) is used as a delimiter between `CONTAINER` and `PATH`, but `:`
    69  could also be in a valid `LOCALPATH`, like `file:name.txt`. This ambiguity is
    70  resolved by requiring a `LOCALPATH` with a `:` to be made explicit with a
    71  relative or absolute path, for example:
    72  
    73      `/path/to/file:name.txt` or `./file:name.txt`
    74  
    75  It is not possible to copy certain system files such as resources under
    76  `/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
    77  
    78  Using `-` as the first argument in place of a `LOCALPATH` will stream the
    79  contents of `STDIN` as a tar archive which will be extracted to the `PATH` in
    80  the filesystem of the destination container. In this case, `PATH` must specify
    81  a directory.
    82  
    83  Using `-` as the second argument in place of a `LOCALPATH` will stream the
    84  contents of the resource from the source container as a tar archive to
    85  `STDOUT`.
    86  
    87  # OPTIONS
    88  **--help**
    89    Print usage statement
    90  
    91  # EXAMPLES
    92  
    93  Suppose a container has finished producing some output as a file it saves
    94  to somewhere in its filesystem. This could be the output of a build job or
    95  some other computation. You can copy these outputs from the container to a
    96  location on your local host.
    97  
    98  If you want to copy the `/tmp/foo` directory from a container to the
    99  existing `/tmp` directory on your host. If you run `docker cp` in your `~`
   100  (home) directory on the local host:
   101  
   102  		$ docker cp compassionate_darwin:tmp/foo /tmp
   103  
   104  Docker creates a `/tmp/foo` directory on your host. Alternatively, you can omit
   105  the leading slash in the command. If you execute this command from your home
   106  directory:
   107  
   108  		$ docker cp compassionate_darwin:tmp/foo tmp
   109  
   110  If `~/tmp` does not exist, Docker will create it and copy the contents of
   111  `/tmp/foo` from the container into this new directory. If `~/tmp` already
   112  exists as a directory, then Docker will copy the contents of `/tmp/foo` from
   113  the container into a directory at `~/tmp/foo`.
   114  
   115  When copying a single file to an existing `LOCALPATH`, the `docker cp` command
   116  will either overwrite the contents of `LOCALPATH` if it is a file or place it
   117  into `LOCALPATH` if it is a directory, overwriting an existing file of the same
   118  name if one exists. For example, this command:
   119  
   120  		$ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /test
   121  
   122  If `/test` does not exist on the local machine, it will be created as a file
   123  with the contents of `/tmp/foo/myfile.txt` from the container. If `/test`
   124  exists as a file, it will be overwritten. Lastly, if `/tmp` exists as a
   125  directory, the file will be copied to `/test/myfile.txt`.
   126  
   127  Next, suppose you want to copy a file or folder into a container. For example,
   128  this could be a configuration file or some other input to a long running
   129  computation that you would like to place into a created container before it
   130  starts. This is useful because it does not require the configuration file or
   131  other input to exist in the container image.
   132  
   133  If you have a file, `config.yml`, in the current directory on your local host
   134  and wish to copy it to an existing directory at `/etc/my-app.d` in a container,
   135  this command can be used:
   136  
   137  		$ docker cp config.yml myappcontainer:/etc/my-app.d
   138  
   139  If you have several files in a local directory `/config` which you need to copy
   140  to a directory `/etc/my-app.d` in a container:
   141  
   142  		$ docker cp /config/. myappcontainer:/etc/my-app.d
   143  
   144  The above command will copy the contents of the local `/config` directory into
   145  the directory `/etc/my-app.d` in the container.
   146  
   147  # HISTORY
   148  April 2014, Originally compiled by William Henry (whenry at redhat dot com)
   149  based on docker.com source material and internal work.
   150  June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
   151  May 2015, updated by Josh Hawn <josh.hawn@docker.com>