github.com/containers/podman/v5@v5.1.0-rc1/docs/source/markdown/podman-cp.1.md (about)

     1  % podman-cp 1
     2  
     3  ## NAME
     4  podman\-cp - Copy files/folders between a container and the local filesystem
     5  
     6  ## SYNOPSIS
     7  **podman cp** [*options*] [*container*:]*src_path* [*container*:]*dest_path*
     8  
     9  **podman container cp** [*options*] [*container*:]*src_path* [*container*:]*dest_path*
    10  
    11  ## DESCRIPTION
    12  **podman cp** allows copying the contents of **src_path** to the **dest_path**. Files can be copied from a container to the local machine and vice versa or between two containers.
    13  If `-` is specified for either the `SRC_PATH` or `DEST_PATH`, one can also stream a tar archive from `STDIN` or to `STDOUT`.
    14  
    15  The containers can be either running or stopped and the *src_path* or *dest_path* can be a file or directory.
    16  
    17  *IMPORTANT: The **podman cp** command assumes container paths are relative to the container's root directory (`/`), which means supplying the initial forward slash is optional and therefore sees `compassionate_darwin:/tmp/foo/myfile.txt` and `compassionate_darwin:tmp/foo/myfile.txt` as identical.*
    18  
    19  Local machine paths can be an absolute or relative value.
    20  The command interprets a local machine's relative paths as relative to the current working directory where **podman cp** is run.
    21  
    22  Assuming a path separator of `/`, a first argument of **src_path** and second argument of **dest_path**, the behavior is as follows:
    23  
    24  **src_path** specifies a file:
    25    - **dest_path** does not exist
    26      - the file is saved to a file created at **dest_path** (note that parent directory must exist).
    27    - **dest_path** exists and is a file
    28      - the destination is overwritten with the source file's contents.
    29    - **dest_path** exists and is a directory
    30      - the file is copied into this directory using the base name from **src_path**.
    31  
    32  **src_path** specifies a directory:
    33    - **dest_path** does not exist
    34      - **dest_path** is created as a directory and the contents of the source directory are copied into this directory.
    35    - **dest_path** exists and is a file
    36      - Error condition: cannot copy a directory to a file.
    37    - **dest_path** exists and is a directory
    38      - **src_path** ends with `/`
    39        - the source directory is copied into this directory.
    40      - **src_path** ends with `/.` (i.e., slash followed by dot)
    41        - the content of the source directory is copied into this directory.
    42  
    43  The command requires **src_path** and **dest_path** to exist according to the above rules.
    44  
    45  If **src_path** is local and is a symbolic link, the symbolic target, is copied by default.
    46  
    47  A *colon* ( : ) is used as a delimiter between a container and its path, it can also be used when specifying paths to a **src_path** or **dest_path** on a local machine, for example, `file:name.txt`.
    48  
    49  *IMPORTANT: while using a *colon* ( : ) in a local machine path, one must be explicit with a relative or absolute path, for example: `/path/to/file:name.txt` or `./file:name.txt`*
    50  
    51  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 the container. In this case, **dest_path** must specify a directory. Using `-` as the **dest_path** streams the contents of the resource (can be a directory) as a tar archive to `STDOUT`.
    52  
    53  Note that `podman cp` ignores permission errors when copying from a running rootless container.  The TTY devices inside a rootless container are owned by the host's root user and hence cannot be read inside the container's user namespace.
    54  
    55  Further note that `podman cp` does not support globbing (e.g., `cp dir/*.txt`).  To copy multiple files from the host to the container use xargs(1) or find(1) (or similar tools for chaining commands) in conjunction with `podman cp`.  To copy multiple files from the container to the host, use `podman mount CONTAINER` and operate on the returned mount point instead (see ALTERNATIVES below).
    56  
    57  ## OPTIONS
    58  
    59  #### **--archive**, **-a**
    60  
    61  Archive mode (copy all UID/GID information).
    62  When set to true, files copied to a container have changed ownership to the primary UID/GID of the container.
    63  When set to false, maintain UID/GID from archive sources instead of changing them to the primary UID/GID of the destination container.
    64  The default is **true**.
    65  
    66  #### **--overwrite**
    67  
    68  Allow directories to be overwritten with non-directories and vice versa.  By default, `podman cp` errors out when attempting to overwrite, for instance, a regular file with a directory.
    69  
    70  ## ALTERNATIVES
    71  
    72  Podman has much stronger capabilities than just `podman cp` to achieve copying files between the host and containers.
    73  
    74  Using standard **[podman-mount(1)](podman-mount.1.md)** and **[podman-unmount(1)](podman-unmount.1.md)** takes advantage of the entire linux tool chain, rather than just cp.
    75  
    76  copying contents out of a container or into a container, can be achieved with a few simple commands. For example:
    77  
    78  To copy the `/etc/foobar` directory out of a container and onto `/tmp` on the host, the following commands can be executed:
    79  
    80  	mnt=$(podman mount CONTAINERID)
    81  	cp -R ${mnt}/etc/foobar /tmp
    82  	podman umount CONTAINERID
    83  
    84  To untar a tar ball into a container, following commands can be executed:
    85  
    86  	mnt=$(podman mount CONTAINERID)
    87  	tar xf content.tgz -C ${mnt}
    88  	podman umount CONTAINERID
    89  
    90  To install a package into a container that
    91  does not have dnf installed, following commands can be executed:
    92  
    93  	mnt=$(podman mount CONTAINERID)
    94  	dnf install --installroot=${mnt} httpd
    95  	chroot ${mnt} rm -rf /var/log/dnf /var/cache/dnf
    96  	podman umount CONTAINERID
    97  
    98  By using `podman mount` and `podman unmount`, one can use all of the
    99  standard linux tools for moving files into and out of containers, not just
   100  the cp command.
   101  
   102  ## EXAMPLES
   103  
   104  Copy a file from the host to a container:
   105  ```
   106  podman cp /myapp/app.conf containerID:/myapp/app.conf
   107  ```
   108  
   109  Copy a file from a container to a directory on another container:
   110  ```
   111  podman cp containerID1:/myfile.txt containerID2:/tmp
   112  ```
   113  
   114  Copy a directory on a container to a directory on the host:
   115  ```
   116  podman cp containerID:/myapp/ /myapp/
   117  ```
   118  
   119  Copy the contents of a directory on a container to a directory on the host:
   120  ```
   121  podman cp containerID:/home/myuser/. /home/myuser/
   122  ```
   123  
   124  Copy a directory on a container into a directory on another:
   125  ```
   126  podman cp containerA:/myapp containerB:/newapp
   127  ```
   128  
   129  Stream a tar archive from `STDIN` to a container:
   130  ```
   131  podman cp - containerID:/myfiles.tar.gz < myfiles.tar.gz
   132  ```
   133  
   134  ## SEE ALSO
   135  **[podman(1)](podman.1.md)**, **[podman-mount(1)](podman-mount.1.md)**, **[podman-unmount(1)](podman-unmount.1.md)**