github.com/docker/docker-ce@v17.12.1-ce-rc2+incompatible/components/cli/docs/reference/commandline/cp.md (about)

     1  ---
     2  title: "cp"
     3  description: "The cp command description and usage"
     4  keywords: "copy, container, files, folders"
     5  ---
     6  
     7  <!-- This file is maintained within the docker/cli GitHub
     8       repository at https://github.com/docker/cli/. Make all
     9       pull requests against that repo. If you see this file in
    10       another repository, consider it read-only there, as it will
    11       periodically be overwritten by the definitive file. Pull
    12       requests which include edits to this file in other repositories
    13       will be rejected.
    14  -->
    15  
    16  # cp
    17  
    18  ```markdown
    19  Usage:  docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-
    20          docker cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH
    21  
    22  Copy files/folders between a container and the local filesystem
    23  
    24  Use '-' as the source to read a tar archive from stdin
    25  and extract it to a directory destination in a container.
    26  Use '-' as the destination to stream a tar archive of a
    27  container source to stdout.
    28  
    29  Options:
    30    -L, --follow-link   Always follow symbol link in SRC_PATH
    31    -a, --archive       Archive mode (copy all uid/gid information)
    32        --help          Print usage
    33  ```
    34  
    35  ## Description
    36  
    37  The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`.
    38  You can copy from the container's file system to the local machine or the
    39  reverse, from the local filesystem to the container. If `-` is specified for
    40  either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from
    41  `STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container.
    42  The `SRC_PATH` or `DEST_PATH` can be a file or directory.
    43  
    44  The `docker cp` command assumes container paths are relative to the container's
    45  `/` (root) directory. This means supplying the initial forward slash is optional;
    46  The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and
    47  `compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can
    48  be an absolute or relative value. The command interprets a local machine's
    49  relative paths as relative to the current working directory where `docker cp` is
    50  run.
    51  
    52  The `cp` command behaves like the Unix `cp -a` command in that directories are
    53  copied recursively with permissions preserved if possible. Ownership is set to
    54  the user and primary group at the destination. For example, files copied to a
    55  container are created with `UID:GID` of the root user. Files copied to the local
    56  machine are created with the `UID:GID` of the user which invoked the `docker cp`
    57  command. However, if you specify the `-a` option, `docker cp` sets the ownership
    58  to the user and primary group at the source.
    59  If you specify the `-L` option, `docker cp` follows any symbolic link
    60  in the `SRC_PATH`.  `docker cp` does *not* create parent directories for
    61  `DEST_PATH` if they do not exist.
    62  
    63  Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
    64  argument of `DEST_PATH`, the behavior is as follows:
    65  
    66  - `SRC_PATH` specifies a file
    67      - `DEST_PATH` does not exist
    68          - the file is saved to a file created at `DEST_PATH`
    69      - `DEST_PATH` does not exist and ends with `/`
    70          - Error condition: the destination directory must exist.
    71      - `DEST_PATH` exists and is a file
    72          - the destination is overwritten with the source file's contents
    73      - `DEST_PATH` exists and is a directory
    74          - the file is copied into this directory using the basename from
    75            `SRC_PATH`
    76  - `SRC_PATH` specifies a directory
    77      - `DEST_PATH` does not exist
    78          - `DEST_PATH` is created as a directory and the *contents* of the source
    79             directory are copied into this directory
    80      - `DEST_PATH` exists and is a file
    81          - Error condition: cannot copy a directory to a file
    82      - `DEST_PATH` exists and is a directory
    83          - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_)
    84              - the source directory is copied into this directory
    85          - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_)
    86              - the *content* of the source directory is copied into this
    87                directory
    88  
    89  The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above
    90  rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
    91  the target, is copied by default. To copy the link target and not the link, specify
    92  the `-L` option.
    93  
    94  A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can
    95  also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local
    96  machine, for example  `file:name.txt`. If you use a `:` in a local machine path,
    97  you must be explicit with a relative or absolute path, for example:
    98  
    99      `/path/to/file:name.txt` or `./file:name.txt`
   100  
   101  It is not possible to copy certain system files such as resources under
   102  `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs-tmpfs), and mounts created by
   103  the user in the container. However, you can still copy such files by manually
   104  running `tar` in `docker exec`. Both of the following examples do the same thing
   105  in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):
   106  
   107  ```bash
   108  $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
   109  ```
   110  
   111  ```bash
   112  $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH -
   113  ```
   114  
   115  Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
   116  The command extracts the content of the tar to the `DEST_PATH` in container's
   117  filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as
   118  the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.