Using Docker Cp Command to Copy Files in Containers

Docker is the most popular platform for building and running software containers - sandboxed environments that are similar to virtual machines, but share your host's operating system kernel. Containers have their own filesystems that contain the packages, source code, and dependencies necessary for an application to run. Occasionally you might want to transfer files between your host and a container's filesystem. In this guide, we'll walk you through understanding docker cp and share some examples for using the command in common scenarios. Let's begin! What is docker cp? The docker cp command allows you to copy files and directories to and from your Docker containers, similar to Unix cp but with some differences and limitations. You can use it whenever you need to interact with a container's content. Its basic syntax is similar to a regular cp: $ docker cp The content at the path referenced by will be copied to . and can either reference a path on your local filesystem or one within a container. Container references use : syntax, where is the container's ID or name and is the path within the container's filesystem. The command can either copy to a container from your host, or from a container to your host. It's not possible to copy files directly between containers; however, you can easily achieve this yourself by running docker cp twice. Understanding docker cp behavior Compared to Unix cp, docker cp has a few significant differences in how it handles the destination path. The behavior varies depending on whether you're copying a file or a directory: For file copies, the destination can be either a new file path or an existing file or directory. If a directory path is given, then the file will be copied into that directory. When a new path is given, then the directory must already exist. For directory copies, a new directory will be created if the destination path doesn't already exist. If the destination does exist, then the new directory will be copied into the existing one, unless the source path ends with /.-in which case, the content of the source directory will be copied into the existing destination directory. Here's a list of the different options: File: /foo → /bar Destination exists? No Copied Path: /bar File: /foo → /bar/demo Destination exists? No (/bar doesn't exist) Copied Path: (Error) File: /foo → /bar Destination exists? Yes, as File Copied Path: /bar File: /foo → /bar Destination exists? Yes, as Directory Copied Path: /bar/foo Directory: /foo → /bar Destination exists? No Copied Path: /bar (contains the content of /foo) Directory: /foo → /bar/demo Destination exists? No (/bar doesn't exist) Copied Path: (Error) Directory: /foo → /bar Destination exists? Yes, as File Copied Path: (Error) Directory: /foo → /bar Destination exists? Yes, as Directory Copied Path: /bar/foo (contains the content of /foo) Directory: /foo/. → /bar Destination exists? Yes, as Directory Copied Path: /bar (contains the content of /foo) When to use docker cp? The docker cp command is useful in several scenarios where you want to interact with a container's filesystem: Debug container issues - You can diagnose problems with containerized apps by copying out logs, traces, or other generated files that help you troubleshoot. Copy out or backup stored files - Many containers create persistent data when they're used, such as uploads to a web application. docker cp lets you make copies of these files on your host, ensuring you have a separate backup before you make changes to your container's deployment. Make config file changes - Some apps dynamically read their configuration files. You can use docker cp to copy in new values without having to restart the container. In general, it's best to avoid using docker cp to apply changes to your containers. Manually altering container filesystems is often an anti-pattern because it can cause drift compared to the container image. Your copied files will also be lost when the container restarts unless the destination path is a bound Docker volume. To summarize, you can safely rely on docker cp to copy files out of containers. This simplifies common development tasks and makes it easier to experiment. However, if changes are required to a container's filesystem, then you should consider rebuilding the image to include your new files-unless you're only modifying config values or other persistent data that are stored in a volume.

Feb 14, 2025 - 13:08

Using Docker Cp Command to Copy Files in Containers

Docker is the most popular platform for building and running software containers - sandboxed environments that are similar to virtual machines, but share your host's operating system kernel. Containers have their own filesystems that contain the packages, source code, and dependencies necessary for an application to run.

Occasionally you might want to transfer files between your host and a container's filesystem. In this guide, we'll walk you through understanding docker cp and share some examples for using the command in common scenarios. Let's begin!

What is docker cp?

The docker cp command allows you to copy files and directories to and from your Docker containers, similar to Unix cp but with some differences and limitations. You can use it whenever you need to interact with a container's content.

Its basic syntax is similar to a regular cp:

$ docker cp

The content at the path referenced by will be copied to . and can either reference a path on your local filesystem or one within a container. Container references use : syntax, where is the container's ID or name and is the path within the container's filesystem.

The command can either copy to a container from your host, or from a container to your host. It's not possible to copy files directly between containers; however, you can easily achieve this yourself by running docker cp twice.

Understanding `docker cp` behavior

Compared to Unix cp, docker cp has a few significant differences in how it handles the destination path. The behavior varies depending on whether you're copying a file or a directory:

For file copies, the destination can be either a new file path or an existing file or directory. If a directory path is given, then the file will be copied into that directory. When a new path is given, then the directory must already exist.
For directory copies, a new directory will be created if the destination path doesn't already exist. If the destination does exist, then the new directory will be copied into the existing one, unless the source path ends with /.-in which case, the content of the source directory will be copied into the existing destination directory.

Here's a list of the different options:

File: /foo → /bar
- Destination exists? No
- Copied Path: /bar
File: /foo → /bar/demo
- Destination exists? No (/bar doesn't exist)
- Copied Path: (Error)
File: /foo → /bar
- Destination exists? Yes, as File
- Copied Path: /bar
File: /foo → /bar
- Destination exists? Yes, as Directory
- Copied Path: /bar/foo
Directory: /foo → /bar
- Destination exists? No
- Copied Path: /bar (contains the content of /foo)
Directory: /foo → /bar/demo
- Destination exists? No (/bar doesn't exist)
- Copied Path: (Error)
Directory: /foo → /bar
- Destination exists? Yes, as File
- Copied Path: (Error)
Directory: /foo → /bar
- Destination exists? Yes, as Directory
- Copied Path: /bar/foo (contains the content of /foo)
Directory: /foo/. → /bar
- Destination exists? Yes, as Directory
- Copied Path: /bar (contains the content of /foo)

When to use docker cp?

The docker cp command is useful in several scenarios where you want to interact with a container's filesystem:

Debug container issues - You can diagnose problems with containerized apps by copying out logs, traces, or other generated files that help you troubleshoot.
Copy out or backup stored files - Many containers create persistent data when they're used, such as uploads to a web application. docker cp lets you make copies of these files on your host, ensuring you have a separate backup before you make changes to your container's deployment.
Make config file changes - Some apps dynamically read their configuration files. You can use docker cp to copy in new values without having to restart the container.

In general, it's best to avoid using docker cp to apply changes to your containers. Manually altering container filesystems is often an anti-pattern because it can cause drift compared to the container image. Your copied files will also be lost when the container restarts unless the destination path is a bound Docker volume.

To summarize, you can safely rely on docker cp to copy files out of containers. This simplifies common development tasks and makes it easier to experiment. However, if changes are required to a container's filesystem, then you should consider rebuilding the image to include your new files-unless you're only modifying config values or other persistent data that are stored in a volume.