How to use docker cp

Jonas Scholz

4 min read 12. Jan. 2024

The docker cp command is a handy tool that lets you move files and folders back and forth between your computer and a Docker container. It's like a bridge that helps you transfer data easily, whether you're copying something from your local machine into a container or pulling files out of a container to your local system.

Let's break down how you can use this command and what you need to know about it.

Basic Usage

The general format for using docker cp looks like this:

docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH
docker cp [OPTIONS] SRC_PATH CONTAINER:DEST_PATH

CONTAINER is the name or ID of your Docker container.
SRC_PATH is the source path, where the file or folder you want to copy is located.
DEST_PATH is the destination path, where you want to put the copied file or folder.

You can use this command to copy files in two directions:

From your local machine to a container.
From a container to your local machine.

The container can be running or stopped; it doesn't matter. Also, when you specify paths within the container, they're considered relative to the container's root directory (/). So, whether you write compassionate_darwin:/tmp/foo/myfile.txt or compassionate_darwin:tmp/foo/myfile.txt, Docker sees them the same way.

On your local machine, paths can be absolute (like /home/user/documents/file.txt) or relative (like documents/file.txt). If you use a relative path, it's based on the directory where you're running the docker cp command.

How It Works

When you copy files, docker cp works a lot like the Unix cp -a command. This means:

If you're copying a directory, it copies everything inside it, including subdirectories.
It tries to keep the original file permissions. But, when copying to a container, files get the UID:GID of the root user inside the container. When copying to your local machine, they get the UID:GID of the user who ran the docker cp command.

There are some options you can use with docker cp:

-a or --archive: This copies all user and group ID information from the source to the destination.
-L or --follow-link: If the source path is a symbolic link, this option makes docker cp copy what the link points to, not just the link itself.
-q or --quiet: This stops the command from showing progress updates during the copy process, which can be useful if you're running it in a script or without a terminal.

Examples

Let's look at some practical examples:

Copying a Local File into a Container:
If you want to copy a file from your local machine into a container, you could use:
```
docker cp ./myfile.txt my_container:/tmp/
```
This command copies myfile.txt from your current directory into the /tmp/ directory inside the my_container container.
Copying Files from a Container to Your Local Path:
To copy files from a container to your local machine, you might do:
```
docker cp my_container:/tmp/myfile.txt ./local_copy.txt
```
This command grabs myfile.txt from the /tmp/ directory in my_container and saves it as local_copy.txt in your current directory.
Copying a File from a Container to Standard Output:
If you want to see the contents of a file directly without saving it, you can use:
```
docker cp my_container:/tmp/myfile.txt -
```
This streams the file's contents as a tar archive to the standard output. You'll need to handle the tar format if you want to use the data.

Special Cases

There are a few things to keep in mind:

You can't copy certain system files like those in /proc, /sys, /dev, or temporary file systems (tmpfs). If you really need to copy these, you might have to use docker exec with tar manually.
If you use - as the source path, it reads a tar archive from standard input and extracts it to the destination path in the container. If you use - as the destination path, it streams the contents of the source as a tar archive to standard output.

Final Thoughts

The docker cp command is a powerful tool for managing files between your local machine and Docker containers. Whether you're setting up a development environment, debugging, or just need to move data around, understanding how to use docker cp can make your Docker workflow much smoother.