HOWTO · Docker
How to Copy Files From Host to Docker Container
Copy a local file or directory into an existing Docker container with docker cp, and choose COPY or a bind mount when it better fits the task.
For a one-time transfer into an existing container, use docker cp with a local source and a container destination:
docker cp ./local-file CONTAINER:/existing-directory/
Replace CONTAINER with the container name or ID. Unlike an interactive docker exec command, docker cp can copy to a running or stopped container. Local relative paths are resolved from the directory in which you run the command, and container paths are rooted at /; the initial slash is optional. See the Docker cp command reference for the complete syntax and rules.
Copy a File Into an Existing Container
The following example copies hello.txt from the current host directory into /opt/ in a container named demo-app. The destination directory must already exist.
docker cp ./hello.txt demo-app:/opt/
When /opt/ exists, Docker preserves the source file name, so the container receives /opt/hello.txt. Use a trailing slash when you mean an existing destination directory. If a file destination already exists, docker cp replaces its contents; use a new name or inspect the destination first when that would be unsafe.
To check the copied file in a running container, run a command directly rather than opening an interactive shell:
docker exec demo-app ls -l /opt/hello.txt
This is a verification command, not expected output: the listing should show /opt/hello.txt when the copy succeeded. docker exec requires a running container, even though docker cp itself also accepts a stopped container.
Copy a Directory or Only Its Contents
docker cp copies directories recursively. The source spelling determines whether Docker places the directory itself in the destination or only the directory’s contents:
# Creates /opt/host-files/ in the container.
docker cp ./host-files demo-app:/opt/
# Copies the contents of host-files into the existing /opt/incoming/ directory.
docker cp ./host-files/. demo-app:/opt/incoming/
In the second command, /opt/incoming/ must already exist. The /. suffix is useful when the destination should receive host-files’ contents without an extra host-files directory. Docker does not create missing parent directories for a destination. A destination ending in / must be an existing directory; otherwise the command fails. These file and directory cases follow the documented docker cp destination rules.
Choose docker cp, Dockerfile COPY, or a Bind Mount
Use the mechanism that matches when the files need to be available:
| Need | Use | Why |
|---|---|---|
| Add a file to one existing container now | docker cp |
Makes a one-time copy into that container’s filesystem. |
| Include files in every image build | Dockerfile COPY |
Adds build-context files to the image, so containers created from that image start with them. |
| Keep a host directory and a running container in sync during development | Bind mount | Shares the host path at runtime rather than creating a separate copy. |
For example, put an application file in an image with a Dockerfile:
COPY ./config.yaml /app/config.yaml
COPY is a build-time instruction, not a way to modify a container that already exists. Its local source paths are interpreted from the build context, so a path outside that context is not available to a normal COPY instruction. The Dockerfile COPY reference explains its build-context and destination behavior.
For repeated live sharing, bind-mount a host directory when the container is created:
docker run --mount type=bind,source=/absolute/host/path,target=/app/input,readonly IMAGE
A bind mount is shared storage, not a copy. Without readonly, a process in the container can modify or delete the host files it can access. Mount a host directory for live file sharing when that is the actual requirement; Docker also documents the bind-mount sharing and permission trade-offs.
Avoid Common docker cp Failures
Check the source and destination paths before copying. A local source path must exist. For a local file copied to a non-existent destination without a trailing /, Docker creates a file at exactly that destination path, but it cannot create absent parent directories. For a directory source, Docker can create the final destination directory when its parent exists; it cannot copy a directory onto a file.
Files copied into a container are owned by the destination user and group by default (normally root:root in the container). Add -a only when preserving the source UID and GID is appropriate for the container’s users. If the local source is a symbolic link, Docker copies the link itself by default; use -L to copy its target instead. Destination permissions can still prevent a useful copy.
Finally, docker cp cannot copy certain container system paths, including resources under /proc, /sys, /dev, temporary filesystems, and user-created mounts. Those cases need a container-specific approach rather than a normal file copy. Review Docker’s documented docker cp limitations before relying on it for system or mounted data.
