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